Live Call Transfer

The Live Call Transfer endpoint transfers an active Asterisk channel. It supports blind transfer through the Asterisk Manager Redirect action and attended transfer through Atxfer.

Endpoint

POST https://pbx.example.com/pbx/openapi.php/calls/transfer?tenant=CANISTRACCI

A writable tenant or global full API key is required. The tenant query parameter must exactly match the tenant code or tenant name; wildcards and read-only keys are rejected. Before sending the manager action, the API verifies that the selected live channel has the selected tenant's account code.

Request Body

Field	Required	Description
channel	One of channel or uniqueid	Exact active Asterisk channel name, for example PJSIP/101-00000042.
uniqueid	One of channel or uniqueid	Asterisk channel UniqueID. If both identifiers are supplied, they must resolve to the same live channel.
destination	Yes	Destination run at priority 1 in the authenticated dialplan context.
type	No	blind or attended. Defaults to blind.
extra_channel	No	Optional second channel sent with a blind Redirect. It must be a different channel on the same PBX node and belong to the same tenant. It is not accepted for an attended transfer.
server	No	PBX node peer name. Use it to limit channel discovery or disambiguate an identical channel name found on more than one node.

The UniqueID returned by the Extension State endpoint can be supplied as uniqueid. Queue State also returns the live channel name for waiting callers.

Blind Transfer

A blind transfer immediately redirects the selected channel to the destination. This is the default type.

curl -X POST "https://pbx.example.com/pbx/openapi.php/calls/transfer?tenant=CANISTRACCI" \
  -H "X-API-Key: TENANT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "uniqueid": "1783680000.25",
    "destination": "200",
    "type": "blind"
  }'

When a dual-channel redirect is required, include the other active channel in extra_channel. Both channels are checked on the same node and against the same tenant before Asterisk receives the request.

Attended Transfer

An attended transfer starts Asterisk's attended-transfer process on the selected channel. The person controlling that channel conducts the consultation and completes or cancels it using the normal Asterisk transfer behavior.

curl -X POST "https://pbx.example.com/pbx/openapi.php/calls/transfer?tenant=CANISTRACCI" \
  -H "X-API-Key: TENANT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "PJSIP/101-00000042",
    "destination": "200",
    "type": "attended"
  }'

Response

{
  "object": "call_transfer",
  "status": "accepted",
  "type": "blind",
  "channel": "PJSIP/101-00000042",
  "uniqueid": "1783680000.25",
  "extra_channel": "",
  "destination": "200",
  "context": "authenticated",
  "priority": 1,
  "server": {
    "id": 1,
    "name": "PBX 01",
    "peername": "pbx01"
  },
  "asterisk": {
    "response": "Success",
    "message": "Redirect successful",
    "actionid": "openapi-transfer-..."
  }
}

status=accepted means Asterisk accepted the manager action. It does not confirm that the destination answered or that the transfer completed successfully.

Channel Selection and Safety

• Channel discovery reads current state directly from the configured PBX nodes.
• Only channels whose Asterisk account code exactly matches the selected tenant can be transferred.
• If the same channel identifier exists on more than one node, the request returns an ambiguity error. Supply server to choose the intended node.
• The channel and optional extra channel are checked again immediately before the transfer action to detect a call that ended or changed during the request.
• The dialplan context and priority are fixed to authenticated,1 and cannot be overridden by the request.

Relevant Errors

HTTP status	Code	Description
400	exact_tenant_required	The tenant is missing, uses a wildcard, or does not exactly match the authenticated tenant.
400	missing_call_identifier	Neither channel nor uniqueid was supplied.
400	invalid_transfer_type	type is not blind or attended.
400	extra_channel_not_allowed	An extra channel was supplied for an attended transfer.
404	channel_not_found	No active channel matches the identifier and tenant.
404	extra_channel_not_found	The extra channel is not active on the selected node for the same tenant.
409	ambiguous_channel	More than one PBX node has a matching channel; supply server.
409	call_state_changed	The call changed between discovery and execution; obtain current channel information and retry.
502	channel_state_unavailable	Live channel state could not be read from the selected PBX nodes.
502	transfer_rejected	Asterisk rejected the Redirect or Atxfer action.