Transfer to a Person

How It Works

A transfer is part of the conversation, not a menu. When the caller asks for a person, or meets a transfer condition you wrote, the agent:

Confirms the destination in one sentence (“I can connect you to our support desk, is that alright?”).
Says the handoff sentence (“One moment, I’m connecting you now.”).
Rings the destination while the caller hears the ringing.
Bridges the two once the person answers, then goes quiet. It’s still one call on your account, with one recording and one webhook.

If nobody answers within timeout_seconds, or the line is busy or declines, the agent picks the conversation back up and offers whatever your instructions say to (carry on now, or a callback). Once max_attempts is used up, it stops offering transfers on that call. The agent picks destinations by label only. It never sees or says the numbers, and it can’t dial the caller’s own number or the number the call runs on.

Transfers work on outbound and inbound campaigns. The person you transfer to sees the campaign’s from_number as the caller ID. Without one, an outbound call shows the number it was dialled from, and an inbound call shows a TopCalls number, never the number the caller rang.

Configure the destinations

Set config.transfer on the campaign. Each destination has an id the agent chooses by, a label the caller hears and you get back, a number in E.164, and a when condition, written in the third person, that tells the agent when to pick it.

{
  "config": {
    "transfer": {
      "targets": [
        {
          "id": "support_desk",
          "label": "our support desk",
          "number": "+40722000001",
          "when": "the caller asks to speak with a person or has a billing dispute the agent cannot settle"
        },
        {
          "id": "sales",
          "label": "a sales colleague",
          "number": "+40722000002",
          "when": "the caller wants a quote or to negotiate a price"
        }
      ],
      "handoff_message": "One moment, I am connecting you to {{target}}.",
      "timeout_seconds": 25,
      "time_limit_seconds": 1800,
      "max_attempts": 1,
      "allowed_prefixes": ["+40"],
      "business_hours": {
        "timezone": "Europe/Bucharest",
        "weekdays": [1, 2, 3, 4, 5],
        "start": "09:00",
        "end": "18:00"
      }
    }
  }
}

Field	Meaning
`targets`	One to five destinations. An `id` is 2 to 32 lowercase letters, digits and underscores, starts with a letter, and is unique. `label` is up to 60 characters, `when` 8 to 240.
`handoff_message`	Sentence used when the agent gives none (up to 200 characters). `{{target}}` becomes the chosen label.
`timeout_seconds`	How long the destination rings before the agent gives up (10 to 60, default 25).
`time_limit_seconds`	Longest the caller and the person stay connected (60 to 3600, default 1800), also capped by the call’s remaining `max_duration`. With under 30 seconds of the call left, the transfer is refused.
`max_attempts`	Transfer attempts per call (1 or 2, default 1).
`allowed_prefixes`	Every destination must start with one of these (default `["+40"]`). Romanian premium and shared-cost ranges (`+4090`, `+4080`) are always refused. A number that breaks either rule returns `400` on save. At transfer time the destination is checked again, against these rules, the same dial policy as any outbound call, and your own TopCalls numbers. A failed check refuses the transfer with `transfer_status: not_allowed`.
`business_hours`	Optional window in which the agent offers transfers, same shape as `inbound_business_hours`. An unknown timezone counts as closed.
`enabled`	`false` turns transfers off without deleting the block.

The block is checked on save and again on every call. Each when goes through the prompt safety review with the rest of the campaign, so a refused condition blocks the call. A change through PATCH /v1/campaigns/{id} reaches calls queued after it, not ones already queued.

Write the prompt for it

The agent already knows how to run a transfer. Your instructions only say when a person is the right outcome and what to offer if nobody picks up:

If the caller asks for a person, or raises a billing dispute you cannot settle,
offer to connect them to our support desk.
If the support desk does not answer, offer to arrange a callback within one business day.

Leave phone numbers out of the instructions, and don’t ask the caller to press a key.

Read the outcome

When a transfer was attempted, the call object (GET /v1/calls/{id}) and the completion webhook carry two more fields:

Field	Value
`transferred_to`	The destination’s label if the caller and the person were connected, otherwise `null`.
`transfer_status`	`completed`, `failed` (no answer, busy or declined, and the agent resumed), `abandoned_by_caller` (the caller hung up while it rang) or `not_allowed` (the transfer was refused before dialling).

A completed transfer sets disposition to Transferred, so subscriptions to call.completed.transferred fire. duration and the recording cover the whole call, time with the person included, and it’s billed as one call. The conversation with the person isn’t transcribed. After the handoff sentence, the transcript has only its closing end item, with end_via: "caller".

Limits

One destination rings at a time.
The person isn’t briefed before the bridge and can’t accept or decline with a key press.
Destinations must be plain phone numbers (+ and 7 to 15 digits, no extension) inside the allowed prefixes. SIP addresses aren’t accepted.

Getting Started

Core Concepts

Guides

Use Cases

Integrations

How It Works

Configure the destinations

Write the prompt for it

Read the outcome

Limits

​How It Works

​Configure the destinations

​Write the prompt for it

​Read the outcome

​Limits

​Related

How It Works

Configure the destinations

Write the prompt for it

Read the outcome

Limits

Related