Scenarios & Limitations
Scenarios, step by step
Each line is what the transferring agent receives, in order, for an extension target. merge and cancel are the control API calls. Note: the legacy init payload precedes initiated on the socket, and the target leg's legacy started / bridged / ended payloads interleave with the keyed states — they are left out below. See Transfer Events.
Consult, then hand over by hanging up
POST /v2/user/transfer to=5002 -> 202
transfer_initiated
transfer_ringing
transfer_answered agent and 5002 talk, customer hears hold music
agent hangs up
transfer_completed customer is with 5002
Consult, merge, then leave
POST /v2/user/transfer to=5002 -> 202
transfer_initiated, transfer_ringing, transfer_answered
merge -> 200 conference sent, mode conference, members 3
transfer_conference all three talk
agent hangs up
transfer_completed customer and 5002 keep talking
Consult, then change your mind
POST /v2/user/transfer to=5002 -> 202
transfer_initiated, transfer_ringing, transfer_answered
cancel -> 200 cancel sent
transfer_cancelled 5002 dropped, customer back with the agent
Cancel while the target is still ringing
POST /v2/user/transfer to=5002 -> 202
transfer_initiated, transfer_ringing
cancel -> 200 cancel sent
transfer_cancelled customer back with the agent
Target does not answer, is busy, or is offline
POST /v2/user/transfer to=5002 -> 202
transfer_initiated
transfer_ringing only when the target is dialed; busy and offline detected before dialing skip it
transfer_failed reason=no_answer | busy | offline customer back with the agent
Target answers, then hangs up during the consult
transfer_initiated, transfer_ringing, transfer_answered
5002 hangs up
transfer_cancelled customer back with the agent
Merged, then the target leaves
transfer_conference
5002 hangs up
transfer_cancelled agent and customer continue; a new transfer can be started directly
Merged, then cancel
transfer_conference
cancel -> 200 cancel sent, mode conference
transfer_cancelled 5002 dropped; agent and customer continue as a normal call
Merged, then the customer leaves
transfer_conference
customer hangs up
transfer_cancelled to is empty; agent and 5002 continue (see known limitations)
Customer hangs up during the consult
transfer_answered
customer hangs up ordinary hangup event of the customer's leg
transfer_cancelled may arrive twice (consult ended, then the target leg's hangup)
Second transfer on the same call
After any terminal state a new POST /v2/user/transfer is accepted. After a merge from which one party already left, the start call first returns the remaining two to a plain call, then dials. While three parties are merged, start is refused with 409 call is merged with a transfer target; cancel it first.
The target agent's side and chained transfers
On the target agent's phone the call arrives like an internal call from the transferring agent, and the SDK's inComingCall event says it is a transfer:
{
"from": "37a27ebe-5df3-47e0-af62-494c2d7a1f30",
"transfer": true,
"transfer_from": "918946076994",
"to_number": "918031404352",
"team_name": "okok_2224257",
"call_id": "88904cff-3454-1240-b4bc-6c92cf01e118"
}
| Field | Meaning |
|---|---|
| from | The transferring agent's user id. |
| transfer | true for a transferred call, false for every other incoming call. |
| transfer_from | The customer's number. |
| to_number | The virtual number: the DID the customer dialled on inbound calls, the organisation's outbound number on outbound and click-to-call calls. |
| team_name | The call's team. |
| call_id | The call id the transfer API accepts for this agent, so the target can transfer the call on with it. |
transfer is a boolean from piopiyjs with the incoming-transfer change; older SDK builds report the header text "true".
The target agent's application also receives its own ordinary call events: started when it rings, answered, hangup, published like an outbound leg (direction "outbound", leg "b", user = the target agent, cmiuuid = the target's leg, conversation_uuid = the original call's conversation id). It gets no cmi_transfer events; those go to the transferring agent only. After a merge, only the transferring agent can cancel; the target's cancel returns 409 no active transfer on this leg.
Chained transfer. The target agent can transfer the call on. They use their own leg's cmiuuid (the call_id of their inComingCall event, the cmiuuid of their own answered event, their call-feed leguuid, or the SDK's getCallId()) with their own token. The cmiuuid in the first agent's transfer_answered event is the first agent's leg, not the target's; do not pass it on.
This works whether the first transfer was completed by the first agent hanging up during the consult, or by the first agent leaving after a merge: in the second case the two remaining parties are released from the room into a plain call when the new transfer starts. A new transfer is refused with 409 call is merged with a transfer target; cancel it first only while three parties are still merged.
Known limitations
- Blind transfer (
type: "blind") is accepted by the API but the switch currently runs it as an attended consult; the events carrytransfer_type: "blind". Do not rely on it; useattendedand hang up to hand over. - Phone-number targets get fewer events. When
tois a phone number and the call is not a call-center queue call (softphone outbound, click-to-call, direct inbound), the platform emitstransfer_initiated,transfer_conferenceandtransfer_completedonly: notransfer_ringing,transfer_answered,transfer_failed, and notransfer_cancelledwhen the target hangs up or is cancelled. On queue callstransfer_ringing,transfer_failedand atransfer_cancelledwhile ringing are emitted too, but still notransfer_answered. Extension targets get the full set. - Terminal events can repeat. When the customer hangs up during the consult,
transfer_cancelledcan arrive twice (once for the consult ending, once for the target leg). Treat a repeated terminal event for the sametransfer_idas a no-op. - Inbound calls through some routes, customer leaves a merged call. On some inbound routes the customer's leg is not the one the switch sees leave the room, so no
transfer_cancelledis emitted when the customer hangs up after amerge. The agent and the target still get the customer's ordinaryhangupevent and keep talking; the next transfer on that call starts normally. - Team transfer is blind only. There is no attended consult with a team; the customer goes into the team and the agent's call ends.
- Team agents do not see that the call is a transfer. A team transfer rings like a new team call; the SDK's
transferflag,transfer_fromand the transferring agent are not set on it (they are for an attended transfer to an agent). mode: "three_way"on a merge reply means the room move did not happen; audio works but the call may end for everyone if the agent hangs up. Report thetransfer_idif it appears.- The SDK's legacy
transfer()/merge()/cancel()use the old socket and DTMF path. They still work on their own but cannot control an API transfer; the app should not mix the two on one call. - Chained transfer by the target agent is implemented as described above; it has been tested less than the single transfer flows.