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

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

The agent app drives transfers through the control surface (admin-gated today; a first-class agent API is on the roadmap):

POST /transfer
{ "callId": "…", "fromUserId": "us_dana",
  "target": { "kind": "user", "id": "us_ravi" },   # kind: user | agent | queue | number | pstn
  "mode": "attended" }

• Blind → returns transferring; the target is dialed and bridged (or the caller recalled on no-answer).
• Attended → returns consulting; the agent is bridged privately to the target. The agent then calls:
  • POST /transfer/complete → bridge the caller to the target, drop the agent.
  • POST /transfer/cancel → drop the target, return the agent to the caller.
  • POST /transfer/3way → merge all three legs (agent + caller + target) into an ad-hoc conference instead of completing or cancelling.

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

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_simultaneous ceiling (default 2), admitted through concurrency control.

Status

Blind, attended, 3-way conference, and queue-target transfer are built end to end: the control plane drives the hold/consult/bridge/recall/merge sequence with the fraud gates, and the edge orchestration is deployed. Agent-initiated transfer via the API above is the supported route; the in-flow transfer node (automated, mid-flow blind transfer, including to a queue) is also available.