Call Transfer Overview
The Call Transfer API lets you transfer a live call from an agent application or a server integration, for the three ways a call reaches an agent:
- Inbound — customer calls a number, a queue rings the agent.
- Outbound — the agent dials from the softphone.
- Admin click-to-call — a server starts the call with the organisation's app secret (Click-To-Call API).
How a transfer works
A transfer is an attended consult:
- The customer is placed on hold with the switch's default hold music.
- The target (another agent or a phone number) is dialed.
- The agent talks to the target first, then does one of:
- Merge — all three parties talk in a private room on the switch.
- Cancel — target dropped, customer back with the agent.
- Hang up — the agent ends their own leg; the customer stays with the target.
Every transfer has a transfer_id, returned by the start call and present in every event about it. Only one transfer can be active per call.
A team transfer is blind instead: the customer goes straight into a team (queue) as if they had called that team, and the agent's call ends at once. See Team Transfer (Blind).
The application never sends DTMF for an API transfer — the switch injects the control keys itself. The old key-press method (*9, 0, #) still works for applications that have not migrated, and cannot interfere with an API-driven transfer.
Before you start
Base URL. Production: https://rest.telecmi.com/v2. Every endpoint is relative to it. Responses are HTTP 200 with the result in the code field, the convention of every /v2 endpoint — check code, not the HTTP status.
Agent token. The transfer endpoints use the agent login token the application already holds, the same token used by the Click-To-Call and hangup APIs. Send it as the x-access-token header or as the token field of the body (a token query parameter is also accepted; the body field wins).
The agent is taken from the token: the token must belong to the agent who is on the call. For testing outside the app:
- Endpoint
POST /v2/user/login - Body
{ "id": "<agent id, e.g. 5001_33336887>", "password": "<agent password>" } - Response
{ "code": 200, "token": "<jwt>", "agent": { "id": "...", "inet_no": ... } }, valid for 30 days
curl -s -X POST https://rest.telecmi.com/v2/user/login \
-H "Content-Type: application/json" \
-d '{ "id": "5001_33336887", "password": "<agent password>" }'
A missing or invalid token on any transfer endpoint returns:
{ "error": true, "code": 407, "message": "Failed to authenticate token." }
Note the shape: message, not msg, and code 407. A token that is expired, signed for another environment, or cut short when copied gets this reply.
Where events arrive
Transfer events reach two places, both optional for the API itself but needed to know the outcome:
- The agent application, over the piopiy socket as the
cmi_transferevent (the piopiyjs SDK re-emits it astransfer). - The organisation's call event webhook, configured in the admin dashboard, as events with
statustransfer_*.
The same webhook also delivers the ordinary call events (waiting, ringing, answered, hangup) that carry the call id the API needs. See Transfer Events.
Which call id to send (cmiuuid)
Both API calls take one parameter to identify the call: cmiuuid. The platform keeps a live-call entry for the agent's leg from the moment the agent's phone rings until that leg ends, and resolves the agent's leg and the switch from any of these ids of the call:
- the agent leg's own id —
cmiuuidof the agent's own events,leguuidon the socket; - the other leg's id — the customer's
cmiuuid; - the
conversation_uuidof the events; - the
call_idof the events — the SIP Call-ID of the agent's phone session, the value the softphone SDK returns fromgetCallId(); - on an inbound or transferred call, the
call_idof the SDK'sinComingCallevent.
Start a transfer only after the agent has answered. After the call ends the entry is removed and the API returns 404.
| Call type | How the call starts | cmiuuid to send |
|---|---|---|
| Inbound | Customer dials a number; the queue rings the agent | cmiuuid of the agent's answered event. The customer's cmiuuid also works. |
| Outbound (agent dials from the softphone) | The agent calls a number from the app | cmiuuid of the customer (leg-b) event, or its conversation_uuid, or its call_id. |
| Admin click-to-call | Server starts the call; the agent's phone rings first | cmiuuid of the agent's leg-a answered event, or conversation_uuid from either leg. |
In the agent application the same id is available without the webhook:
| Source | Field |
|---|---|
Socket call-feed event of the agent's call | Inbound and click-to-call: leguuid is the agent's leg. Softphone outbound: uuid is the agent's leg and leguuid the customer's. Both resolve. |
| Softphone SDK (piopiyjs) | getCallId(), or call_id of the inComingCall event |
| Any call event on the webhook | cmiuuid |
Why a lookup can fail
404 cmiuuid not found for agent <id> in org <org> (is the token for the agent who answered?) means no live call with that id belongs to the agent in the token. The usual causes:
- the token is another agent's (for example the transferring agent's token used with the target agent's leg, see Scenarios);
- the call already ended (the live-call entry is removed at hangup), or the request was sent before the agent's phone rang;
- the id is from a different organisation.
The API makes up to three lookup attempts 300 ms apart, so a transfer sent on the answered event works. When the live-call store itself does not answer, both endpoints reply 503 call store unavailable, retry in a moment instead of 404; that reply can take a few seconds and is not retried automatically.
The APIs at a glance
| API | Endpoint | Choice |
|---|---|---|
| Start a transfer (attended) | POST /v2/user/transfer to agent extension / phone number | Start a Transfer |
| Start a team transfer (blind) | POST /v2/user/transfer with team instead of to | Team Transfer (Blind) |
| Merge / Cancel | POST /v2/user/transfer/control | Merge & Cancel |
| Complete the transfer | POST /v2/c2c/hangup (agent hangs up) | Start a Transfer |