Skip to main content

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/json or application/x-www-form-urlencoded

Sample Request​

{
"cmiuuid": "d3c4a9f0-7b21-4e0a-9f6e-1c2b3a4d5e6f",
"action": "merge"
}

Request Parameters​

ParameterTypeRequiredDescription
tokenstringNoAgent login token, when not sent in the x-access-token header (or as a token query parameter).
*cmiuuidstringYesThe same call id used to start the transfer.
*actionstringYes"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​

codemsgMeaningWhat to do
400cmiuuid param missingNo call id given.Fix the request.
400action must be merge or cancelUnknown action.Fix the request.
407Failed to authenticate token. (field message)Missing or invalid token.Log in again.
404cmiuuid 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.
404channel not foundThe agent's channel is gone: the call ended.Treat the call as over.
409no active transfer on this legNothing 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.
409target has not answered yetmerge while the target is still ringing.Wait for transfer_answered, or cancel.
409already mergedmerge while the agent is still in the room, including after the target or the customer left it.Nothing to do, or cancel.
503call store unavailable, retry in a momentLive-call store timeout.Retry after a second.
503switch unreachableThe switch did not answer within 5 s.Retry once.
503switch errorThe 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.
503switch returned an unexpected replyAs for the start call.Platform issue; report it.

What each action does in each state​

Call statePOST /v2/user/transfermergecancelagent hangs up
No transfer activeStarts the consult. 202.409 no active transfer on this leg409 no active transfer on this legNormal end of call.
Target ringing409 transfer already in progress409 target has not answered yetStops 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 progressAll 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 leg409 no active transfer on this legNormal end of call.
Merged (three in the room)409 call is merged with a transfer target; cancel it first409 already mergedTarget dropped; agent and customer continue as a normal call. transfer_cancelled.Agent leaves; customer and target keep talking. transfer_completed.
Merged, target already leftBrings agent and customer back to a normal call, then starts the new consult. 202 (or 409 cannot leave the merged call: ...).409 already mergedBrings agent and customer back to a normal call; nothing is dropped. 200 cancel sent.Normal end of call.
Merged, customer already leftBrings 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 mergedBrings 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.