Skip to main content

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"
}
FieldMeaning
fromThe transferring agent's user id.
transfertrue for a transferred call, false for every other incoming call.
transfer_fromThe customer's number.
to_numberThe virtual number: the DID the customer dialled on inbound calls, the organisation's outbound number on outbound and click-to-call calls.
team_nameThe call's team.
call_idThe 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 carry transfer_type: "blind". Do not rely on it; use attended and hang up to hand over.
  • Phone-number targets get fewer events. When to is a phone number and the call is not a call-center queue call (softphone outbound, click-to-call, direct inbound), the platform emits transfer_initiated, transfer_conference and transfer_completed only: no transfer_ringing, transfer_answered, transfer_failed, and no transfer_cancelled when the target hangs up or is cancelled. On queue calls transfer_ringing, transfer_failed and a transfer_cancelled while ringing are emitted too, but still no transfer_answered. Extension targets get the full set.
  • Terminal events can repeat. When the customer hangs up during the consult, transfer_cancelled can arrive twice (once for the consult ending, once for the target leg). Treat a repeated terminal event for the same transfer_id as 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_cancelled is emitted when the customer hangs up after a merge. The agent and the target still get the customer's ordinary hangup event 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 transfer flag, transfer_from and 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 the transfer_id if 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.