Merge & Cancel
Control a transfer in progress: merge all three parties into one call, or cancel the transfer and return the customer to the agent.
- Endpoint
POST /v2/user/transfer/control - Base URL
https://rest.telecmi.com - Content-Type
application/jsonorapplication/x-www-form-urlencoded
Sample Request
{
"cmiuuid": "d3c4a9f0-7b21-4e0a-9f6e-1c2b3a4d5e6f",
"action": "merge"
}
Request Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| token | string | No | Agent login token, when not sent in the x-access-token header (or as a token query parameter). |
| *cmiuuid | string | Yes | The same call id used to start the transfer. |
| *action | string | Yes | "merge": bring the customer into the consult so all three talk, in a private room on the switch; whoever leaves afterwards, the other two keep talking. "cancel": drop the target and return the customer to the agent; after a merge, drop the target and continue as a normal two-party call. Case-insensitive. "conference" is an alias of "merge". |
curl -s -X POST https://rest.telecmi.com/v2/user/transfer/control \
-H "Content-Type: application/json" -H "x-access-token: <jwt>" \
-d '{ "cmiuuid": "d3c4a9f0-7b21-4e0a-9f6e-1c2b3a4d5e6f", "action": "merge" }'
curl -s -X POST https://rest.telecmi.com/v2/user/transfer/control \
-H "Content-Type: application/json" -H "x-access-token: <jwt>" \
-d '{ "cmiuuid": "d3c4a9f0-7b21-4e0a-9f6e-1c2b3a4d5e6f", "action": "cancel" }'
Sample Response
merge:
{
"code": 200,
"msg": "conference sent",
"mode": "conference",
"members": 3
}
mode is "conference" when the three parties are in the switch room (the normal case) and members is the number of parties in it. mode "three_way" (no members) means the switch could not move the parties into the room and left them in the basic three-way of the consult; audio works, but if the agent then hangs up the call may end for everyone. Log it and report the transfer_id if it appears. A transfer_conference event follows either way.
cancel during the consult:
{ "code": 200, "msg": "cancel sent" }
cancel after a merge:
{ "code": 200, "msg": "cancel sent", "mode": "conference" }
A transfer_cancelled event follows. See Transfer Events.
Error Codes
code | msg | Meaning | What to do |
|---|---|---|---|
400 | cmiuuid param missing | No call id given. | Fix the request. |
400 | action must be merge or cancel | Unknown action. | Fix the request. |
407 | Failed to authenticate token. (field message) | Missing or invalid token. | Log in again. |
404 | cmiuuid not found for agent <id> in org <org> (is the token for the agent who answered?) | No live call with this id belongs to the agent in the token. | See Why a lookup can fail. |
404 | channel not found | The agent's channel is gone: the call ended. | Treat the call as over. |
409 | no active transfer on this leg | Nothing to merge or cancel: no consult is running and nothing is merged. Also returned after the consult ended by itself (target hung up, no answer, busy), and to a target agent who sends cancel after a merge. | Start a new transfer if wanted. |
409 | target has not answered yet | merge while the target is still ringing. | Wait for transfer_answered, or cancel. |
409 | already merged | merge while the agent is still in the room, including after the target or the customer left it. | Nothing to do, or cancel. |
503 | call store unavailable, retry in a moment | Live-call store timeout. | Retry after a second. |
503 | switch unreachable | The switch did not answer within 5 s. | Retry once. |
503 | switch error | The switch could not inject the merge or cancel key, or could not release the parties from the room. | Retry once; if it repeats, report the cmiuuid. |
503 | switch returned an unexpected reply | As for the start call. | Platform issue; report it. |
What each action does in each state
| Call state | POST /v2/user/transfer | merge | cancel | agent hangs up |
|---|---|---|---|---|
| No transfer active | Starts the consult. 202. | 409 no active transfer on this leg | 409 no active transfer on this leg | Normal end of call. |
| Target ringing | 409 transfer already in progress | 409 target has not answered yet | Stops ringing the target; customer back with the agent. transfer_cancelled. | Customer waits and is bridged to the target when it answers. transfer_completed. |
| Consult (agent and target talking, customer on hold) | 409 transfer already in progress | All three joined in a room. transfer_conference. | Target dropped; customer back with the agent. transfer_cancelled. | Customer bridged to the target. transfer_completed. |
| Consult ended by itself (target hung up, no answer, busy) | Starts a new consult. 202. | 409 no active transfer on this leg | 409 no active transfer on this leg | Normal end of call. |
| Merged (three in the room) | 409 call is merged with a transfer target; cancel it first | 409 already merged | Target dropped; agent and customer continue as a normal call. transfer_cancelled. | Agent leaves; customer and target keep talking. transfer_completed. |
| Merged, target already left | Brings agent and customer back to a normal call, then starts the new consult. 202 (or 409 cannot leave the merged call: ...). | 409 already merged | Brings agent and customer back to a normal call; nothing is dropped. 200 cancel sent. | Normal end of call. |
| Merged, customer already left | Brings agent and target back to a normal call, then starts a new consult with the target as the party on hold. 202 (or 409 cannot leave the merged call: ...). | 409 already merged | Brings agent and target back to a normal call; nothing is dropped. 200 cancel sent. | Normal end of call. |
While merged, key presses on any of the three phones are ignored by the room. During the consult, an API-driven transfer binds merge and cancel to DTMF keys that phones and the agent app never send, so the legacy key presses (*9, 0, #) cannot merge or cancel it. Only the API can, and only with the transferring agent's token: the target agent's cancel returns 409 no active transfer on this leg.