Call Transfer
An agent on a live call can transfer it, handing the caller to another agent, user, queue, or an external number. SIP.IO supports both blind (one-shot) and attended (consultative) transfers, with anti-fraud gates on PSTN transfers.
Blind vs. attended
Section titled “Blind vs. attended”| Mode | What happens |
|---|---|
blind | One shot: the caller is held, the target is dialed, and the two are bridged the moment the target answers, with the transferring agent dropping out immediately. If the target doesn’t answer, the caller is recalled to the agent. |
attended (consultative) | The agent consults first: the caller is held while the agent and the target talk privately, then the agent completes the transfer (bridge caller ↔ target) or cancels to return to the caller. |
Initiating a transfer
Section titled “Initiating a transfer”Your agent app drives a transfer with one endpoint on the public API:
curl -X POST 'https://api.sip.io/v1/calls/mine/transfer' \ -H 'x-api-key: sk_…' -H 'content-type: application/json' \ -d '{ "action": "start", "mode": "attended", "target": { "kind": "user", "id": "us_ravi" } }'target.kind is one of user, agent, queue or number. mine means the call the credential’s own user is on; with the calls:all scope a supervisor app can name any live call in the account.
- Blind (
mode: "blind"): the target rings while the caller holds, then the caller is connected to it. If nobody answers, the caller stays with you. - Attended (
mode: "attended"): the caller holds while you talk to the target. Then call the same endpoint again with:action: "complete": connect the caller to the target and drop out.action: "cancel": drop the target and return to the caller.action: "3way": merge all three legs (you, the caller and the target) into an ad-hoc conference.
The reply’s callId is the caller’s leg. Keep it for the follow-up complete/cancel/3way calls, because after a first transfer it can differ from the id you started with.
The phone’s own Transfer button
Section titled “The phone’s own Transfer button”Agents don’t need an app to transfer. Pressing Transfer on a SIP desk phone or softphone does a blind transfer through the same engine (the phone’s REFER is handled by SIP.IO, never passed through raw), so it gets the same fraud gates and the same call records.
| Status | error | Meaning |
|---|---|---|
403 | not_your_call | Without calls:all, only your own call or your own consult. |
404 | no_active_call · call_not_found | No live call by that id. |
409 | not_transferable · transfer_in_progress · in_conference · not_consulting | The call can’t take this action right now. |
Transfer into a queue. Set target.kind: "queue" to drop the caller back into an ACD queue; they re-enter the queue’s distribution (no new outbound leg) and the next available agent picks up. |
Anti-fraud gates
Section titled “Anti-fraud gates”Because a transfer can place an outbound leg, PSTN transfers are gated:
allow_pstn_blind_transfer(sip_user, default off): a user may not blind-transfer a call to a PSTN number unless this is set. This blocks the classic fraud of calling a cheap destination and blind-transferring it to an expensive one.- Per-user concurrency: the transfer’s outbound leg counts toward the user’s
max_simultaneousceiling (default2), admitted through concurrency control.
Status
Section titled “Status”Blind, attended, 3-way conference and queue-target transfer are live on the /v1/calls/{id}/transfer API and from the phone’s own Transfer button. The in-flow transfer node (an automated, mid-flow blind transfer, including to a queue) is also available. Calls placed by click to call, the dialer and callbacks can be transferred like any other.