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/jsonorapplication/x-www-form-urlencoded
Sample Request
{
"cmiuuid": "d3c4a9f0-7b21-4e0a-9f6e-1c2b3a4d5e6f",
"to": "5002",
"type": "attended"
}
Request Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| token | string | No | Agent login token, when not sent in the x-access-token header. A token query parameter is accepted too; the body field wins over both. |
| *cmiuuid | string | Yes | The call id, see Overview. |
| *to | string | Yes | Target: 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. |
| type | string | No | "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
| Property | Type | Description |
|---|---|---|
| code | number | 202 when the transfer was accepted. |
| msg | string | "transfer started" |
| transfer_id | string | Id of this transfer, present in every event about it. |
Error Codes
code | msg | Meaning | What to do |
|---|---|---|---|
400 | cmiuuid param missing | No call id given. | Fix the request. |
400 | to must be an extension or phone number | to is missing, has characters other than digits and a leading +, or is too long. | Fix the request. |
400 | type must be attended or blind | Unknown type. | Fix the request. |
407 | Failed to authenticate token. (field message, with error: true) | 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 call was found but its channel is already gone on the switch: the call just ended. | Treat the call as over. |
409 | transfer already in progress | A consult is running on this call (target ringing or talking). | Wait for a terminal event, or cancel. |
409 | call is merged with a transfer target; cancel it first | The previous transfer was merged and all three parties are still in the call. | Send cancel, then start again. |
409 | cannot 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. |
503 | call store unavailable, retry in a moment | The live-call store did not answer (timeout or unreachable). Not a "not found"; the reply can take a few seconds. | Retry after a second. |
503 | switch unreachable | The switch did not answer within 5 s. | Retry once. |
503 | switch error | The 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. |
503 | switch 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.