Transfer to a Person

How It Works

A transfer is part of the conversation, not a menu. When a caller asks for a person, or reaches a point you described as a transfer condition, the agent:

Confirms the destination with the caller in one sentence (“I can connect you to our support desk, is that alright?”).
Says the handoff sentence (“One moment, I am connecting you now.”).
Rings the destination number. The caller hears the ringing.
Bridges the caller and the person once they answer. The agent goes quiet; the call stays one call on your account, with one recording and one webhook.

If the person does not answer within timeout_seconds, is busy or declines, the agent resumes the conversation and offers what you configured as the fallback (continuing now, or a callback). Once max_attempts is reached the agent no longer offers a transfer on that call. The caller’s own number is never handed to the agent as a destination and the destination numbers are never spoken: the agent only ever chooses between the destinations you configured, by their labels.

Transfers work on standard campaigns, outbound and inbound alike. A campaign in the realtime mode does not offer them. The person receiving the call sees the campaign’s own number as the caller ID.

Configure the destinations

Set config.transfer on the campaign. Each destination has a stable id (what the agent chooses between), a label (what the caller hears and what you get back), the number in E.164, and a when condition written in the third person, which is the rule the agent follows 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. Ids are lowercase letters, digits and underscores.
`handoff_message`	Fallback sentence when the agent gives none. `{{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`.
`max_attempts`	Transfer attempts per call (1 or 2, default 1).
`allowed_prefixes`	Every destination must start with one of these. Default `["+40"]`. A number outside the list is rejected with `422`.
`business_hours`	Optional window in which transfers are offered. Same shape as `inbound_business_hours`. Outside it the agent does not offer a transfer.
`enabled`	Set `false` to switch transfers off without deleting the block.

The block is validated when you save the campaign and again on every call. Use PATCH /v1/campaigns/{id} to change it; the next call picks it up.

Write the prompt for it

The agent already knows how to operate the transfer. Your campaign instructions should say when a person is the right outcome and what to offer when the person cannot be reached. Two lines are usually enough:

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.

Do not put phone numbers in the instructions. Do not ask the caller to press a key.

Read the outcome

The call object (GET /v1/calls/{id}) and the completion webhook carry two extra fields when a transfer was attempted:

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

A completed transfer sets disposition to Transferred. Webhook subscriptions receive call.completed.transferred. The call’s duration covers the whole call, including the time the caller spent with the person, and is billed as one call. The recording covers the whole call as well. The transcript stops at the handoff sentence: the conversation with the person is not transcribed.

Limits

One destination is rung at a time; there is no simultaneous ring.
The person is not briefed before the bridge and cannot accept or decline with a key press.
The caller’s own number cannot be shown to the person; the campaign number is used.
Destinations must be ordinary phone numbers in the allowed prefixes. SIP addresses are not 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