VoIP.infoThe independent guide to business communications.
VoIP.info Guide

Asterisk PJSIP_TRANSFER_HANDLING: core versus ARI-owned REFER transfers

Choose who owns one incoming SIP REFER without confusing endpoint permission, event delivery, application action, dialog correlation or the final transfer result.

Reviewed 2026-10-13Current Asterisk PJSIP_TRANSFER_HANDLING, ARI transfer handling, ChannelTransfer data-model, res_pjsip endpoint, remote attended-transfer and CHANNEL documentation reviewed October 13, 2026; PJSIP_TRANSFER_HANDLING is documented since Asterisk 20.13.0, 21.8.0 and 22.3.0, while installed branch, maintenance release, loaded modules, endpoint allow_transfer policy, channel ownership, ARI subscription, SIP dialog correlation, application actions, peer behavior and transfer result remain deployment specific; no PBX, endpoint, channel, bridge, ARI client, event, REFER, NOTIFY, INVITE, packet or transfer was inspected or testedAdvancedDocumentation based · not lab tested

Separate endpoint permission from transfer ownership

The res_pjsip endpoint allow_transfer option determines whether SIP REFER transfers are allowed for that endpoint. PJSIP_TRANSFER_HANDLING() chooses how an allowed incoming REFER is handled on one PJSIP channel. Permission and ownership are related but not interchangeable.

Record the endpoint, channel name, unique ID, bridge, Call-ID, direction and collection time. A permitted REFER does not prove that core handling completed, an ARI event reached a consumer or a transferred call connected.

Use only the documented handling modes

Current documentation defines core as the default: Asterisk handles attended and blind transfers. ari-only causes Asterisk to generate ARI events for an incoming SIP REFER instead. The function is documented since 20.13.0, 21.8.0 and 22.3.0, so the installed branch and maintenance release must be checked before relying on it.

The function is write-only. Preserve the exact place and time of the write rather than claiming a later read proved the mode. Apply it on the channel that will receive the REFER, before the transfer attempt.

Place ari-only before the channel enters application control

The ARI guide documents three ways to establish ari-only: an endpoint set_var, dialplan before the channel enters Stasis, or a variable supplied when an ARI channel is created. Each path produces a channel-scoped value at a different lifecycle point.

A variable on a caller, Local-channel sibling or later replacement channel is not proof that the REFER-receiving PJSIP leg carried it. Use CHANNEL(endpoint) plus channel and bridge identifiers to preserve ownership.

Treat ChannelTransfer as input, not completion

The documented ChannelTransfer event contains transfer state plus refer_to and referred_by structures. Attended-transfer correlation can include requested destination, SIP Call-ID and resolved channel or bridge identifiers; blind transfer usually supplies the requested destination. Missing IDs can be legitimate when another Asterisk or proxy owns the other dialog.

An event means Asterisk exposed transfer information to ARI. It does not prove that the application authorized the target, created a replacement channel, changed bridge membership or completed a transfer.

Make the ARI application own the whole transaction

In ari-only, the ARI application must take action. For a blind transfer, the documented workflow removes the affected channel from its bridge, creates and dials a channel to the requested destination, then adds the new channel to the bridge. Attended transfers require correlation across the referenced and referring dialogs.

Keep target validation, authorization, originate result, bridge mutation, NOTIFY progress and final connected parties as separate evidence. A 202 response accepts the REFER transaction; it is not the transferred-call result.

Prove one transfer end to end and retain rollback

Use one authorized blind or attended transfer with exact timestamps. Correlate the incoming REFER, ChannelTransfer event, ARI consumer receipt, policy decision, new channel, bridge mutation, SIP responses and NOTIFY messages, endpoint display and final audio path. Verify a control endpoint that remains under core.

Return to core or remove the scoped override if the ARI application cannot assume full transfer ownership. Protect dialed destinations and identity headers in shared evidence. This guide is documentation-derived; no Asterisk host, ARI client, REFER or transfer was tested.

Asterisk dialplan — delegate one PJSIP channel transfer to ARI
[from-transfer-lab]
exten => _X.,1,Set(PJSIP_TRANSFER_HANDLING()=ari-only)
 same => n,Stasis(transfer-controller)
 same => n,Hangup()

Sources & applicability

Primary references for the technical details above. Operational examples and planning checklists are VoIP.info editorial guidance.

Examples require adaptation to your topology. No live PBX or hardware testing is claimed.

Continue your research

Hub

Asterisk

Understand the programmable PBX and follow the Asterisk 22 LTS documentation baseline.

Explore topic →
Guide · Asterisk 22 LTS

Asterisk PJSIP: understand the configuration objects

Connect endpoint behavior, authentication, contacts and transport without collapsing them into one account setting.

Read guide →
Guide · Current Asterisk feature-transfer architecture, Asterisk 22 features, FEATUREMAP, BlindTransfer and AttendedTransfer references plus AMI and CEL transfer-event specifications reviewed October 6, 2026; no PBX, endpoint, phone, channel, bridge, dialplan destination, feature code, DTMF sequence, native SIP transfer, recording, identity, media path or call was inspected or tested

Asterisk call transfers: blind, attended and bridge evidence

Separate core feature-code transfers, native SIP or phone behavior and dialplan transfer applications, then preserve the original bridge, consultation leg, destination and final bridge as distinct evidence.

Read guide →
Guide · Current Asterisk ARI configuration and getting-started guidance, latest Applications API, Certified Asterisk 22.8 Events API and Asterisk 22 REST data models reviewed October 10, 2026; no Asterisk host, ARI user, application, WebSocket, subscription, filter, event, resource, client handler or call tested

Asterisk ARI events and subscriptions: scope, filters and WebSocket ownership

Design ARI event delivery by separating application registration, automatic and explicit subscriptions, subscribe-all scope, event filters, connection ownership and client processing.

Read guide →
Guide · Current first-party Asterisk ARI bridge, mixing, holding, operations, event-model and recording documentation reviewed October 9, 2026; no HTTP server, ARI user, Stasis application, bridge, channel, endpoint, socket, packet, media frame, playback, recording, DTMF result or call was inspected or tested

Asterisk ARI bridges: ownership, membership and media topology

Choose a mixing or holding bridge deliberately, keep it inside the intended Stasis application and prove channel membership separately from media behavior.

Read guide →
Guide · Current Asterisk 23 ARI channel, Stasis and bridge documentation reviewed October 9, 2026; no HTTP server, TLS profile, WebSocket, ARI user, application, host, endpoint, channel, bridge, media path or call was inspected or tested

Asterisk ARI channel origination: create, dial and prove application control

Choose direct originate or create-then-dial, retain client identifiers, and separate HTTP acceptance, Stasis ownership, answer, bridge membership, media and application outcome.

Read guide →
Guide · Current Asterisk PJSIP_ENDPOINT and CHANNEL function documentation, res_pjsip endpoint configuration reference, object-relationship guidance and PJSIP troubleshooting guidance reviewed October 13, 2026; PJSIP_ENDPOINT is documented since Asterisk 12.0.0, while installed branch, maintenance release, loaded modules, configuration backend, object names, defaults, endpoint identification, channel association, contacts, signaling and media remain deployment specific; no PBX, module, configuration, endpoint, identify object, channel, SIP exchange, packet or call was inspected or tested

Asterisk PJSIP endpoint inspection: configuration fields, channel identity and proof

Read one loaded endpoint field without confusing configuration, inbound endpoint identification, AoR location, a live channel or negotiated SIP and media state.

Read guide →
Troubleshooting · Current Asterisk PJSIP_TRANSFER_HANDLING, ARI transfer handling, ChannelTransfer data-model, res_pjsip endpoint, remote attended-transfer and CHANNEL documentation reviewed October 13, 2026; PJSIP_TRANSFER_HANDLING is documented since Asterisk 20.13.0, 21.8.0 and 22.3.0, while installed branch, maintenance release, loaded modules, endpoint allow_transfer policy, channel ownership, ARI subscription, SIP dialog correlation, application actions, peer behavior and transfer result remain deployment specific; no PBX, endpoint, channel, bridge, ARI client, event, REFER, NOTIFY, INVITE, packet or transfer was inspected or tested

Asterisk PJSIP transfer event is missing or the transfer stalls

Trace release support, endpoint permission, channel timing, ARI subscription, REFER correlation, application action, NOTIFY progress and the final bridge before changing global transfer policy.

Read guide →