Skip to main content

Start a Transfer

Start an attended transfer of a live call to another agent extension or to a phone number. Before calling this endpoint, read Call Transfer Overview to know which cmiuuid to send.

  • Endpoint POST /v2/user/transfer
  • Base URL https://rest.telecmi.com
  • Content-Type application/json or application/x-www-form-urlencoded

Sample Request​

{
"cmiuuid": "d3c4a9f0-7b21-4e0a-9f6e-1c2b3a4d5e6f",
"to": "5002",
"type": "attended"
}

Request Parameters​

ParameterTypeRequiredDescription
tokenstringNoAgent login token, when not sent in the x-access-token header. A token query parameter is accepted too; the body field wins over both.
*cmiuuidstringYesThe call id, see Overview.
*tostringYesTarget: an agent extension, for example 5002, or a phone number in international format without spaces, for example 919876543210. Digits only, at most 20; a leading + is allowed with at most 19 digits after it.
typestringNo"attended" (default). "blind" is accepted but currently runs as attended, see Known Limitations. Case-insensitive.
curl -s -X POST https://rest.telecmi.com/v2/user/transfer \
-H "Content-Type: application/json" -H "x-access-token: <jwt>" \
-d '{ "cmiuuid": "d3c4a9f0-7b21-4e0a-9f6e-1c2b3a4d5e6f", "to": "5002", "type": "attended" }'

Sample Response​

{
"code": 202,
"msg": "transfer started",
"transfer_id": "b1f4e2a0-1c9d-4f7e-8a3b-2d5c6e7f8a90"
}

202 means the switch accepted the transfer and is about to dial the target. It does not mean the target answered. The outcome arrives as events (transfer_ringing, transfer_answered, transfer_failed, ...). Keep the transfer_id; every event about this transfer carries it.

Properties​

PropertyTypeDescription
codenumber202 when the transfer was accepted.
msgstring"transfer started"
transfer_idstringId of this transfer, present in every event about it.

Error Codes​

codemsgMeaningWhat to do
400cmiuuid param missingNo call id given.Fix the request.
400to must be an extension or phone numberto is missing, has characters other than digits and a leading +, or is too long.Fix the request.
400type must be attended or blindUnknown type.Fix the request.
407Failed to authenticate token. (field message, with error: true)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 call was found but its channel is already gone on the switch: the call just ended.Treat the call as over.
409transfer already in progressA consult is running on this call (target ringing or talking).Wait for a terminal event, or cancel.
409call is merged with a transfer target; cancel it firstThe previous transfer was merged and all three parties are still in the call.Send cancel, then start again.
409cannot leave the merged call: <detail>One party had already left the merged call and the platform failed to bring the remaining two back to a plain call before starting the new transfer.Retry once; if it repeats, report the cmiuuid.
503call store unavailable, retry in a momentThe live-call store did not answer (timeout or unreachable). Not a "not found"; the reply can take a few seconds.Retry after a second.
503switch unreachableThe switch did not answer within 5 s.Retry once.
503switch errorThe switch answered with an internal error: the transfer script could not be started on the agent leg, or the platform's switch credentials are misconfigured.Retry once; if it repeats, report the cmiuuid.
503switch returned an unexpected reply (old transfer.lua on the switch?)The switch's reply was not the JSON of this API: an older transfer handler, or a runtime error in front of it.Platform issue; report it.

Completing a transfer (agent hangs up)​

There is no "complete" action. To hand the customer over, the agent hangs up their own leg: in the app, the normal end-call button; from a server, the existing hangup endpoint with the same cmiuuid.

curl -s -X POST https://rest.telecmi.com/v2/c2c/hangup \
-H "Content-Type: application/json" -H "x-access-token: <jwt>" \
-d '{ "cmiuuid": "d3c4a9f0-7b21-4e0a-9f6e-1c2b3a4d5e6f" }'

This works during the consult (the customer is bridged to the target; if the target is still ringing, they are bridged when it answers) and after a merge (the agent leaves the room; customer and target keep talking). Either way the transferring agent receives transfer_completed.

/v2/c2c/hangup resolves the call the same way as the transfer API (any id of the call) and replies { "code": 200, "msg": "call ended" } as soon as the hangup is sent to the switch, 400 cmiuuid param missing or 404 cmiuuid not found on bad input, and 503 call store unavailable, retry in a moment when the live-call store does not answer.