Transfers to a person

An agent can hand a live call to a person at your business: a caller who asks for someone, a complaint, a lead ready to buy. The agent tells the caller it is connecting them, Tone rings the person, and the person hears a short spoken brief before they take the call. If nobody takes it, the caller is back with the agent, which carries on where it left off.

A transfer is set up in two places: destinations (who may be rung) and the agent's transfer setting (when it rings them).

Destinations

A destination is a person or a desk, with a number and the language they are briefed in. It must be verified before any agent can transfer to it: Tone calls the number and speaks a six-digit code, and you send the code back. That proves the number is reachable and that whoever answers it agreed to take calls.

curl -X POST "$TONE_API/v1/transfer-destinations" \
  -H "Authorization: Bearer $TONE_KEY" -H "Content-Type: application/json" \
  -d '{
    "key": "delivery_team",
    "label": "Delivery team",
    "e164": "+919876543210",
    "language": "hi-IN",
    "hours": [{ "days": "mon-sat", "from": "09:30", "to": "19:00" }]
  }'

curl -X POST "$TONE_API/v1/transfer-destinations/$DEST/verify"  -H "Authorization: Bearer $TONE_KEY"
curl -X POST "$TONE_API/v1/transfer-destinations/$DEST/confirm" -H "Authorization: Bearer $TONE_KEY" \
  -H "Content-Type: application/json" -d '{ "code": "482913" }'

• hours are in IST. Outside them the agent tells the caller nobody is available instead of dialling. Leave them out to take transfers at any time.
• Changing the number puts the destination back to pending until it is verified again.
• POST …/disable stops transfers to it without deleting anything.

The agent's setting

callSettings.transfer on the agent names the destinations it may use and, for each, when to use it — in plain words the agent reads:

{
  "transfer": {
    "destinations": [
      { "destinationId": "…", "when": "The caller wants a new delivery date.", "fallbackDestinationId": "…" },
      { "destinationId": "…", "when": "A question about a charge on their card." }
    ],
    "defaultDestinationId": null,
    "requestPhrases": true,
    "dtmfKey": null,
    "ringTimeoutSeconds": 20,
    "handoff": "cold",
    "recordHumanSegment": true,
    "preTransferLine": { "text": null },
    "afterMissLine": { "text": null }
  }
}

Like every setting, it takes effect when you publish the agent.

What happens on a call

1. The agent says the pre-transfer line and lets go of the call. When the person's part is recorded, the line ends by telling the caller so.
2. Tone rings the destination from your number. The caller hears a ringback tone; the person hears a brief — who is calling about what — and on Plivo numbers presses 1 to take the call.
3. Taken: the caller and the person talk. The call ends when either hangs up.
4. Not taken (no answer, busy, declined, outside hours): the caller is back with the agent, which says the after-miss line and carries on. A call can make at most two attempts.
5. Called off: a caller who says "no, wait" (or "रुको", "રહેવા દો") while the line plays stays with the agent, and the attempt ends caller_cancelled. Once the person's phone is ringing it is too late to call it off.

Transfers run on Plivo and Exotel numbers and on your own SIP trunk. A VoiceLink number can transfer once Tone has moved its calls onto Tone's SIP gateway — ask support; its transfers are then warm, like a SIP trunk's, and the person's minutes bill at ₹2.00.

Warm handoff

With handoff: "warm", on calls over Plivo numbers, the caller never waits on hold for someone who may not answer:

1. The agent says it is checking whether someone can take the call, and keeps talking with the caller.
2. Tone rings the person as a call of their own. They hear the brief and press 1. After they press 1 they hear a second short part — the caller's name, when the call carries a customer_name value, and the agent's note — and wait a moment.
3. The agent tells the caller the person is on the line, and the two are connected.

If the person does not answer, declines, or never presses 1, the caller was with the agent the whole time: it says the after-miss line and carries on. A caller who says "no, wait" while the person's phone is ringing or they are listening to the brief calls it off; once they have pressed 1 it is too late. After about 20 quiet seconds the agent says once that it is still trying.

Every other call — Exotel numbers, and calls whose agent is set to cold — is handed over cold.

Transfers run on calls over Plivo and Exotel numbers, and on calls over your own SIP trunk. On test keys and in the dashboard's test calls the transfer is simulated: nobody is rung, the agent says the line and lets go, and the attempt is taken after 3 seconds and ends 10 seconds after it began, with the same webhooks a real one sends.

What the person gets

Besides the spoken brief, each transfer webhook carries links.handoff: a page showing what the caller has said so far, the values the call was placed with, and a short summary, written while the phone rings. Anyone with the link can open it for 24 hours, so send it to the person taking the call and nowhere else. See Webhooks for call.transfer_started, call.transferred and call.transfer_failed.

On your own SIP trunk

On a call over your own SIP trunk, the person is rung over that same trunk — through your carrier, from the number the call is on — and every transfer is warm: the agent keeps talking with the caller while the person hears the brief and presses 1, then the two are connected. Nothing on the trunk side changes; the trunk needs an outbound host, as for any call the agent places.

The person's minutes bill at ₹1.50 a minute — no agent runs for them, and your carrier, not Tone's, carries their leg. Their part is recorded and transcribed live, as on Plivo, unless the agent's recordHumanSegment is off.

A second person

A destination can name a fallback: another of the agent's destinations, tried when nobody at the first takes the call (no answer, busy, declined, or no key pressed). On Plivo numbers it is rung straight away — on a cold transfer the caller keeps hearing the hold tone, on a warm one the agent says it is trying someone else and carries on. A call still makes at most two attempts, so the fallback is tried once, and only if it is verified and inside its hours. The first attempt ends failed with its outcome; the second is a separate attempt. Exotel numbers make one attempt per call and do not use fallbacks.

Starting a transfer from your backend

Your own systems can hand a live call to a person — a CRM that spots a high-value caller, a supervisor's button:

curl -X POST "$TONE_API/v1/calls/$CALL/transfer" \
  -H "Authorization: Bearer $TONE_KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "destinationId": "…", "reason": "qualified_lead", "note": "Ready to pay today." }'

The agent does it exactly as if it had decided to: the caller hears the same line, the person the same brief, and every rule still applies — the destination must be one of the agent's, verified and inside its hours, and a call makes at most two attempts. The answer comes back once the agent has started (or could not start) the transfer:

• accepted: true and transfer, the attempt (trigger: "api").
• accepted: false and a refusal — outside_hours, in_progress, attempts_exhausted and so on. Not an error: nothing was started.
• 409 call_not_live when no agent is on the call: it has ended, is not answered yet, or was already handed to a person.

On a BYO call, which runs your own bot rather than a Tone agent, the destination may be any of yours, and "handoff": "warm" keeps the caller with your bot until the person accepts. Your bot can ask for the transfer itself, too, with a transfer frame.

Afterwards

The call is still one call: one row, one transcript, one bill.

• GET /v1/calls/{id} carries the latest attempt as transfer — its status, outcome, times, how long the person talked, and brief, the words the person heard before pressing 1. A warm attempt is mode: "consult" and also carries acceptedAt, when the person pressed 1. GET /v1/calls/{id}/transfers lists every attempt.
• The transcript runs on past the handoff. The person's lines have the role human_agent; the caller's stay user. On Plivo and on your own SIP trunk they are transcribed live; on Exotel from Exotel's own recording, a few minutes after the call.
• Each attempt's recordings are separate files of the call:
  • GET /v1/calls/{id}/transfers/{transferId}/recording — the part with the person: a stereo WAV on Plivo and on your own SIP trunk (the caller left, the person right), Exotel's two-channel MP3 on Exotel.
  • GET /v1/calls/{id}/transfers/{transferId}/return-recording — the agent's part after an attempt nobody took, when the caller came back.
  • The part before the handoff is the call's own GET /v1/calls/{id}/recording.
• The call's summary and outputs are written again once the person's part is in, so they cover the whole conversation.

Billing

The agent's part of the call and the time the caller waited while the person was rung bill at the call's normal rate. The time the caller and the person talked bills at ₹2.00 a minute (₹1.50 on your own SIP trunk): no agent was running. It is still one wallet debit per call. The person's phone leg is a cost to Tone, not a line on your bill.