# Transfers to a person

Source: https://docs.usetone.ai/transfers

> Let an agent hand a live call to someone at your business, and what the person and your systems get.

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.

```bash
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:

```json
{
  "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 }
  }
}
```

| Field | |
|---|---|
| `requestPhrases` | Transfer as soon as the caller clearly asks for a person, without waiting for the agent to decide |
| `dtmfKey` | A keypad key that transfers to the default destination. Never `9`, the opt-out key |
| `ringTimeoutSeconds` | 10–60. A declined call keeps ringing for the whole of this on Indian mobiles, so keep it short |
| `destinations[].fallbackDestinationId` | Who to try next when nobody at this destination takes the call — another of the agent's destinations. See [A second person](#a-second-person) |
| `handoff` | `cold` (the default): the agent lets go and the caller waits while the person is rung. `warm`: the caller stays with the agent until the person has pressed 1 — see [Warm handoff](#warm-handoff) |
| `recordHumanSegment` | Record and transcribe the part after the handoff. The caller and the person are both told |
| `preTransferLine`, `afterMissLine` | What the agent says as it transfers, and when nobody took the call. `null` uses Tone's lines |

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](#on-your-own-sip-trunk).
A VoiceLink number can transfer once Tone has moved its calls onto Tone's SIP gateway — ask
[support](/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-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](/webhooks) for `call.transfer_started`, `call.transferred` and
`call.transfer_failed`.

## On your own SIP trunk

On a call over [your own SIP trunk](/sip-trunking), 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:

```bash
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](/tone-media-streams#handing-the-call-to-a-person), 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.