Transfer Events
Each state change of a transfer is delivered on the transferring agent's socket and, when the organisation has a call event webhook, to that webhook. Both carry the transfer_id returned by the start call. This section gives the complete JSON of every payload as the application receives it.
States
| State | Socket code | Webhook status | Meaning |
|---|---|---|---|
initiated | 100 | transfer_initiated | The switch started the transfer on the agent's leg. It is produced independently of the HTTP reply, so it can arrive a moment before or after the 202. |
ringing | 180 | transfer_ringing | The platform is dialing the target (it is not the target device's own ringing signal). |
answered | 200 | transfer_answered | The target answered; agent and target are talking, customer on hold. merge is now allowed. |
conference | 201 | transfer_conference | merge accepted; all three parties talk. |
completed | 202 | transfer_completed | The agent hung up; the customer is (or, if the target was still ringing, will be) with the target. Terminal. |
cancelled | 487 | transfer_cancelled | The transfer ended without completing: the agent cancelled, the target hung up, the customer hung up during the consult, or after a merge the target or the customer left the room. The customer stays with the agent (or the agent with the target when the customer left). Terminal. |
failed | 480 | transfer_failed | The consult never connected. reason says why, see failure reasons. Terminal. |
A team transfer produces only initiated and then completed (or failed).
Terminal states are completed, cancelled and failed. Key the transfer UI on transfer_id and clear it on the first terminal state; treat a repeated terminal event for the same transfer_id as a no-op (see known limitations). Extension targets produce the full set; phone-number targets produce fewer events (see known limitations).
Socket event cmi_transfer (agent application)
The transferring agent's socket receives cmi_transfer in its own room (wssip<agent id>, joined by the piopiyjs SDK on connect). The SDK re-emits it as transfer:
piopiy.on('transfer', (e) => {
if (!e.transfer_id) return; // legacy payload, see below
switch (e.state) {
case 'answered': /* enable merge */ break;
case 'completed':
case 'cancelled':
case 'failed': /* clear the transfer UI */ break;
}
});
| Field | Type | Meaning |
|---|---|---|
| state | string | One of the states above. |
| code | number | Numeric code of the state. |
| transfer_id | string | Id of this transfer. |
| to | string | Target extension or number as given to the API. Empty on the cancelled that reports the customer leaving a merged call. |
| type | string | attended or blind, as given to the API. |
| reason | string | Why it failed; empty for every other state. |
| cmiuuid | string | The transferring agent's own leg, the id to use with the API. |
Complete payloads, one per state, for agent 5159_2224257 transferring to extension 5282:
{"state":"initiated","code":100,"transfer_id":"d1dccb48-5cba-4d47-9e78-8b0470c18a38","to":"5282","type":"attended","reason":"","cmiuuid":"46c81098-4b17-4295-9172-397a4c0d2b11"}
{"state":"ringing","code":180,"transfer_id":"d1dccb48-5cba-4d47-9e78-8b0470c18a38","to":"5282","type":"attended","reason":"","cmiuuid":"46c81098-4b17-4295-9172-397a4c0d2b11"}
{"state":"answered","code":200,"transfer_id":"d1dccb48-5cba-4d47-9e78-8b0470c18a38","to":"5282","type":"attended","reason":"","cmiuuid":"46c81098-4b17-4295-9172-397a4c0d2b11"}
{"state":"conference","code":201,"transfer_id":"d1dccb48-5cba-4d47-9e78-8b0470c18a38","to":"5282","type":"attended","reason":"","cmiuuid":"46c81098-4b17-4295-9172-397a4c0d2b11"}
{"state":"completed","code":202,"transfer_id":"d1dccb48-5cba-4d47-9e78-8b0470c18a38","to":"5282","type":"attended","reason":"","cmiuuid":"46c81098-4b17-4295-9172-397a4c0d2b11"}
{"state":"cancelled","code":487,"transfer_id":"d1dccb48-5cba-4d47-9e78-8b0470c18a38","to":"5282","type":"attended","reason":"","cmiuuid":"46c81098-4b17-4295-9172-397a4c0d2b11"}
{"state":"failed","code":480,"transfer_id":"d1dccb48-5cba-4d47-9e78-8b0470c18a38","to":"5282","type":"attended","reason":"offline","cmiuuid":"46c81098-4b17-4295-9172-397a4c0d2b11"}
The cancelled that reports the customer leaving a merged call has an empty to:
{"state":"cancelled","code":487,"transfer_id":"d1dccb48-5cba-4d47-9e78-8b0470c18a38","to":"","type":"attended","reason":"","cmiuuid":"46c81098-4b17-4295-9172-397a4c0d2b11"}
Webhook (organisation call event URL)
Posted to the organisation's call event URL with the configured method, like the other call events. One flat payload for every state:
| Field | Meaning |
|---|---|
| type | Always event. |
| status | transfer_ + state, see states. |
| transfer_id | Id of this transfer. |
| transfer_type | attended or blind, as given to the API. |
| user | The transferring agent. |
| team | The call's team: the queue name on inbound calls; on softphone outbound calls the agent's outbound team, or default_<app_id> when the agent has none; on click-to-call the out_team of the request, or none. |
| to | Target extension or number. Empty on the transfer_cancelled that reports the customer leaving a merged call. |
| cmiuuid | The transferring agent's leg, the id used to start the transfer. |
| conversation_uuid | The customer's leg on inbound calls. On outbound calls the transferring agent's leg has no conversation id, so this field is absent from the states produced on that leg (initiated, ringing, conference, completed, failed, and the cancelled of a consult that ended) and present only on answered and on the cancelled derived from the target's or the customer's hangup. |
| from | The customer's number on inbound calls. On outbound and click-to-call calls the organisation's outbound caller id (the DID the call was made from). |
| app_id | The organisation id. |
| time | Unix time in milliseconds. |
| custom | The organisation's custom webhook value, none when not configured. Absent when the value is null. |
| reason | Only on transfer_failed, see failure reasons. |
Complete payloads, one per state, inbound call answered by 5159_2224257 and transferred to 5282:
{"type":"event","status":"transfer_initiated","transfer_id":"d1dccb48-5cba-4d47-9e78-8b0470c18a38","transfer_type":"attended","user":"5159_2224257","team":"okok_2224257","to":"5282","cmiuuid":"46c81098-4b17-4295-9172-397a4c0d2b11","conversation_uuid":"9def3ef9-b9bf-4903-80bf-dbb4d6013bb9","from":"919894396168","app_id":2224257,"time":1789636527000,"custom":"none"}
{"type":"event","status":"transfer_ringing","transfer_id":"d1dccb48-5cba-4d47-9e78-8b0470c18a38","transfer_type":"attended","user":"5159_2224257","team":"okok_2224257","to":"5282","cmiuuid":"46c81098-4b17-4295-9172-397a4c0d2b11","conversation_uuid":"9def3ef9-b9bf-4903-80bf-dbb4d6013bb9","from":"919894396168","app_id":2224257,"time":1789636528200,"custom":"none"}
{"type":"event","status":"transfer_answered","transfer_id":"d1dccb48-5cba-4d47-9e78-8b0470c18a38","transfer_type":"attended","user":"5159_2224257","team":"okok_2224257","to":"5282","cmiuuid":"46c81098-4b17-4295-9172-397a4c0d2b11","conversation_uuid":"9def3ef9-b9bf-4903-80bf-dbb4d6013bb9","from":"919894396168","app_id":2224257,"time":1789636533800,"custom":"none"}
{"type":"event","status":"transfer_conference","transfer_id":"d1dccb48-5cba-4d47-9e78-8b0470c18a38","transfer_type":"attended","user":"5159_2224257","team":"okok_2224257","to":"5282","cmiuuid":"46c81098-4b17-4295-9172-397a4c0d2b11","conversation_uuid":"9def3ef9-b9bf-4903-80bf-dbb4d6013bb9","from":"919894396168","app_id":2224257,"time":1789636545100,"custom":"none"}
{"type":"event","status":"transfer_completed","transfer_id":"d1dccb48-5cba-4d47-9e78-8b0470c18a38","transfer_type":"attended","user":"5159_2224257","team":"okok_2224257","to":"5282","cmiuuid":"46c81098-4b17-4295-9172-397a4c0d2b11","conversation_uuid":"9def3ef9-b9bf-4903-80bf-dbb4d6013bb9","from":"919894396168","app_id":2224257,"time":1789636590400,"custom":"none"}
{"type":"event","status":"transfer_cancelled","transfer_id":"d1dccb48-5cba-4d47-9e78-8b0470c18a38","transfer_type":"attended","user":"5159_2224257","team":"okok_2224257","to":"5282","cmiuuid":"46c81098-4b17-4295-9172-397a4c0d2b11","conversation_uuid":"9def3ef9-b9bf-4903-80bf-dbb4d6013bb9","from":"919894396168","app_id":2224257,"time":1789636560900,"custom":"none"}
{"type":"event","status":"transfer_failed","transfer_id":"d1dccb48-5cba-4d47-9e78-8b0470c18a38","transfer_type":"attended","user":"5159_2224257","team":"okok_2224257","to":"5282","cmiuuid":"46c81098-4b17-4295-9172-397a4c0d2b11","conversation_uuid":"9def3ef9-b9bf-4903-80bf-dbb4d6013bb9","from":"919894396168","app_id":2224257,"time":1789636529300,"custom":"none","reason":"offline"}
The webhook also keeps delivering the ordinary call events of every leg during the transfer. The target's leg appears as outbound-style agent events with user = the target agent (see the target agent's side). Match the transfer events by transfer_id, and the legs by cmiuuid and conversation_uuid.
Failure reasons
transfer_failed carries reason (socket field reason, webhook field reason, socket code 480). Failures decided before dialing arrive right after initiated, without a ringing.
reason | When | Meaning | Suggested handling |
|---|---|---|---|
invalid_number | before dialing, or on dial | to is not an extension of this organisation, is empty, or the number could not be routed (unallocated, no route, invalid format). | Fix the destination; do not retry the same value. |
blocked | before dialing | The organisation is inactive or has no outbound number configured. | Do not retry; check the organisation's settings. |
offline | before dialing, or on dial | The target extension has no registered device, or its device did not respond (SIP 408, not registered, network out of order). | Pick another agent, or retry after the target's app reconnects. |
busy | before dialing, or on dial | The target is already on a call, or its device answered busy (SIP 486) or the route was congested. | Retry later or pick another agent. |
no_answer | on dial | The target rang for the full ring time and did not answer (SIP 480 included). | Retry later or pick another agent. |
rejected | on dial | The target declined the call (SIP 403 / 603). | Pick another agent. |
switch_error | either | The switch could not run the transfer (script or dial-string error, or an unmapped hangup cause such as SIP 503). | Retry once; if it repeats, report the transfer_id. |
A consult that connected and then ended without completing is never a failure: it is transfer_cancelled. Errors before the transfer starts are responses of the start call, not events.
Call events that carry the id
These are the ordinary call events the application already receives; they are where the cmiuuid for the transfer API comes from.
Socket call-feed when the agent's leg starts ringing (action ch-c), delivered to the agent's own room. leguuid is the id to send for inbound and click-to-call calls; on a softphone outbound call the payload describes the customer leg, so leguuid is the customer's leg and uuid the agent's leg (both are accepted). The same payload can arrive twice for one leg; deduplicate on leguuid. The answered (ch-s) and hangup (ch-d) call-feeds carry the same ids.
Inbound call, agent 5159_2224257 rung by the queue (leguuid is the agent's leg — send this; parent_uuid the customer's leg — also accepted; call_id the SIP Call-ID of the agent's phone session; uuid is an internal originator channel — do not use it):
{"to":918031404352,"call_id":"7c1f0f2a-3d5e-4b8a-9c1e-2f3a4b5c6d7e","cmi_switch":"203.0.113.10","parent_uuid":"9def3ef9-b9bf-4903-80bf-dbb4d6013bb9","cmi_time":1789636333000,"direction":"outbound","time":1789636332612,"uuid":"b7e1c9a2-5d3f-4c8e-9a6b-0f2d4e6a8c10","agent":"5159_2224257","inetno":"2224257","group":"okok_2224257","from":"919894396168","action":"ch-c","leguuid":"46c81098-4b17-4295-9172-397a4c0d2b11","leg":"b","notify":true,"notify_url":"https://example.com/webhook","notify_method":"post","notify_custom":"null","call_state":"started","cmi_type":"event"}
Softphone outbound call to 919894396168 (the payload is the customer leg; uuid is the agent's leg, leguuid the customer's leg, call_id the agent's SIP Call-ID — all three are accepted):
{"call_id":"v4cidv9tcja1l6j3haem","extra_params":"{}","cmi_switch":"203.0.113.10","to":"919894396168","leg":"b","cmi_time":1789636503000,"direction":"outbound","time":1789636502497,"uuid":"46c81098-4b17-4295-9172-397a4c0d2b11","agent":"5159_2224257","inetno":"2224257","group":"okok_2224257","from":"+918031404352","action":"ch-c","leguuid":"d05b52bf-1f00-42db-99a6-8189a520a7a6","out":"yes","outbound":"yes","notify":true,"notify_url":"https://example.com/webhook","notify_method":"post","notify_custom":"null","call_state":"started","cmi_type":"event"}
Click-to-call, agent leg a (ruuid is the request_id of the click-to-call response) and customer leg b. On leg a, leguuid and uuid are both the agent's leg (send either). On leg b, uuid is the agent's leg and leguuid the customer's leg:
{"call_id":"8e1f2a3b-4c5d-6e7f-8a9b-0c1d2e3f4a5b","ruuid":"b7d4f9e2c1a6","extra_params":"{}","cmi_switch":"203.0.113.10","to":"919876543210","leg":"a","cmi_time":1789636503000,"direction":"outbound","time":1789636502497,"uuid":"3c7e9a12-5b4d-4f0e-8a21-6d9f0b1c2e34","agent":"5159_2224257","inetno":"2224257","from":"+918031404352","action":"ch-c","leguuid":"3c7e9a12-5b4d-4f0e-8a21-6d9f0b1c2e34","out":"yes","outbound":"yes","notify":true,"notify_url":"https://example.com/webhook","notify_method":"post","notify_custom":"null","call_state":"started","cmi_type":"event"}
{"ruuid":"b7d4f9e2c1a6","extra_params":"{}","cmi_switch":"203.0.113.10","to":"+919876543210","leg":"b","cmi_time":1789636510000,"direction":"outbound","time":1789636502497,"uuid":"3c7e9a12-5b4d-4f0e-8a21-6d9f0b1c2e34","agent":"5159_2224257","inetno":"2224257","group":"none","from":"+918031404352","action":"ch-c","leguuid":"7a1f4c9e-2d3b-4e5f-9a6b-1c2d3e4f5a6b","out":"yes","outbound":"yes","notify":true,"notify_url":"https://example.com/webhook","notify_method":"post","notify_custom":"null","call_state":"started","cmi_type":"event"}
Webhook call events. The answered event of each leg, as posted to the organisation's URL. Inbound, customer leg then agent leg:
{"type":"event","direction":"inbound","conversation_uuid":"9def3ef9-b9bf-4903-80bf-dbb4d6013bb9","cmiuuid":"9def3ef9-b9bf-4903-80bf-dbb4d6013bb9","from":"919894396168","app_id":2224257,"time":1789636336104,"to":"+918031404352","custom":"none","status":"answered"}
{"leg":"b","type":"event","team":"okok_2224257","user":"5159_2224257","conversation_uuid":"9def3ef9-b9bf-4903-80bf-dbb4d6013bb9","cmiuuid":"46c81098-4b17-4295-9172-397a4c0d2b11","direction":"outbound","from":"919894396168","to":"+918031404352","app_id":2224257,"time":1789636336104,"custom":"none","status":"answered"}
Softphone outbound, customer leg (the only leg published):
{"call_id":"v4cidv9tcja1l6j3haem","leg":"b","type":"event","user":"5159_2224257","cmiuuid":"d05b52bf-1f00-42db-99a6-8189a520a7a6","direction":"outbound","callerid":"+918031404352","app_id":2224257,"time":1789636509000,"custom":"none","extra_params":{},"status":"answered","to":"919894396168","conversation_uuid":"46c81098-4b17-4295-9172-397a4c0d2b11"}
Click-to-call, agent leg a then customer leg b:
{"call_id":"8e1f2a3b-4c5d-6e7f-8a9b-0c1d2e3f4a5b","leg":"a","type":"event","user":"5159_2224257","cmiuuid":"3c7e9a12-5b4d-4f0e-8a21-6d9f0b1c2e34","direction":"outbound","callerid":"+918031404352","app_id":2224257,"time":1789636506000,"custom":"none","extra_params":{},"request_id":"b7d4f9e2c1a6","status":"answered","to":"919876543210","conversation_uuid":"3c7e9a12-5b4d-4f0e-8a21-6d9f0b1c2e34"}
{"leg":"b","type":"event","user":"5159_2224257","cmiuuid":"7a1f4c9e-2d3b-4e5f-9a6b-1c2d3e4f5a6b","direction":"outbound","callerid":"+918031404352","app_id":2224257,"time":1789636515000,"custom":"none","extra_params":{},"request_id":"b7d4f9e2c1a6","status":"answered","to":"919876543210","conversation_uuid":"3c7e9a12-5b4d-4f0e-8a21-6d9f0b1c2e34"}
cmiuuid of the agent's own event is the id to send. conversation_uuid and, on outbound calls, call_id are accepted as well.