> ## Documentation Index
> Fetch the complete documentation index at: https://docs.callers.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Call transfers

> Hand a live call from your AI agent to a person: a phone number, a SIP destination, or a human operator queue, with or without a spoken handoff summary.

A transfer hands a live call from the agent to a person: your sales desk, a support line, a SIP extension in your PBX, or a [Human Operators](https://docs.callers.ai/documentation/human-operators/overview.md) queue in Callers. Use transfers when a contact is ready to buy, asks for a human, or needs help the agent shouldn't give.

Callers supports two kinds of transfer:

| Type | What happens | Use it when |
| - | - | - |
| **Cold transfer** | The agent says its transfer phrase and connects the call. The receiver starts with no context. | The receiver doesn't need background, or the line is a general queue. |
| **Warm transfer** | Callers generates a short spoken summary of the conversation and plays it during the handoff. | The receiver should know who's calling and why before they speak. |

<ol />

## Add a transfer to your script

**1. Add a Call Transfer step**

In the script editor, add a **Call Transfer** step where the agent should hand off, for example in a block the agent reaches when the contact asks for a human.

**2. Write the transfer phrase**

In **Call Transfer Phrase**, write what the agent says before connecting, for example: "I'll connect you with a specialist now. Please hold for a moment."

**3. Choose the destination**

Use the **Phone / SIP** tab for a number or SIP address, or the **Human operator** tab for a queue. See [Destinations](#destinations).

**4. Choose the caller ID**

Set **Caller ID for Forwarded Call**. See [Caller ID](#caller-id).

**5. Optional: turn on Warm Transfer**

Turn on **Warm Transfer** and configure the handoff message. See [Warm transfer](#warm-transfer).

**6. Test**

Save and make a [test call](https://docs.callers.ai/documentation/build-your-agent/testing-your-agent.md) that reaches the transfer step. Make sure the destination answers.

> [!TIP]
>
> Make the conditions for a transfer explicit in the script, for example a [scenario](https://docs.callers.ai/documentation/build-your-agent/agent-scenarios.md) triggered by "Can I talk to a person?". You can also transfer automatically when a [guardrail](https://docs.callers.ai/documentation/build-your-agent/instructions-and-guardrails.md) is triggered.

## Destinations

| Destination | How to enter it | Example |
| - | - | - |
| **Phone number** | An international number in E.164 format on the **Phone / SIP** tab. | `+14155550123` |
| **Contact field** | A [variable](https://docs.callers.ai/documentation/build-your-agent/agent-variables.md) on the **Phone / SIP** tab. Callers resolves it per contact, for example to the contact's account manager. | `{{account_manager_phone}}` |
| **SIP URI** | A SIP address starting with `sip:` on the **Phone / SIP** tab. Use this to reach an extension or queue in your own PBX. | `sip:sales@pbx.example.com` |
| **Human operator queue** | A queue selected on the **Human operator** tab. The call rings operators who are signed in to Callers. | Support queue |

Callers detects the type from what you type: a value with `{{ }}` is a contact field, a value starting with `sip:` is a SIP URI, and a value starting with a digit or `+` is a phone number.

> [!NOTE]
>
> Transfers to SIP URIs need a [SIP integration](https://docs.callers.ai/documentation/integrations/sip.md). Human operator queues are set up on the [Human Operators](https://docs.callers.ai/documentation/human-operators/overview.md) page.

## Caller ID

**Caller ID for Forwarded Call** decides which number the receiver sees:

| Option | The receiver sees | Best for |
| - | - | - |
| **Agent's number** (default) | The number the agent called from or was called on. | Receivers who should know the call came through the AI agent. |
| **Contact's number** | The contact's own number. | Teams that want to call the contact back directly or match the caller in their CRM. |

> [!WARNING]
>
> Showing the contact's number on an outbound leg depends on your carrier allowing it. Some carriers reject or overwrite caller IDs that don't belong to your account. Test before you rely on it.

With **Send SIP Headers** on (the default, under **General Settings** → [**Technical Settings**](https://docs.callers.ai/documentation/build-your-agent/agent-setup.md#technical-settings-voice-agents)), Callers adds the contact's variables as custom SIP headers on outbound calls and transfers, so your PBX can screen-pop the contact's details.

## Warm transfer

With **Warm Transfer** on, Callers writes a short summary of the conversation when the transfer starts and plays it as audio during the handoff.

### Configure the handoff message

In the Call Transfer step:

| Setting | Options | What it does |
| - | - | - |
| Handoff prompt | Free text, supports variables | Tells the AI what to include in the summary, for example "Summarize the caller's issue, their account number, and what they've already tried in two sentences." |
| **Play warm transfer message to** | **Receiver only**, **Both parties** (default) | **Receiver only** plays the summary to the receiver before the contact is connected. **Both parties** plays it after both are connected, so the contact hears it too. |
| **When to play handoff message** | **When call is connected** (default), **When ⁕ is pressed** | Shown for **Both parties**. With **When ⁕ is pressed**, the summary plays only when the receiver presses the star key, so they can greet the contact first. |

> [!NOTE]
>
> For calls made without SIP (for example, on Twilio numbers), the handoff message can only play to the receiver as soon as the call is connected, and it isn't included in the call recording. **Both parties** and **When ⁕ is pressed** need SIP.

> [!WARNING]
>
> **Receiver only** is not recommended when the destination is a call queue or IVR: the message may play before a person answers. Use **Both parties** with **When ⁕ is pressed**, or trigger the summary with the API.

### Write a good handoff prompt

* Ask for one to three sentences. Long summaries delay the conversation.
* Name the facts the receiver needs: the contact's name, the reason for the call, and anything already collected.
* Reference variables for exact values, for example `{{order_id}}`, rather than relying on the AI to repeat them.

### Play the summary with the API

If your own phone system decides when the receiver is ready, for example when an agent in your contact center accepts the call, play the warm transfer summary with the API at that moment. The [Subaccounts and SIP](https://docs.callers.ai/api-reference/guides/subaccounts-and-sip.md) API guide shows the full flow.

**sessionId** `string` *required*

The session ID of the original call (the `sessionId` field in [webhook payloads](https://docs.callers.ai/documentation/webhook/webhook-payload.md)).

**agentOnly** `boolean` (default: false)

`true` plays the summary only to the receiver. `false` plays it to both the receiver and the contact.

```bash cURL theme={"dark"}
curl -X POST https://api.callers.ai/call/SESSION_ID/warm-transfer-summary \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "agentOnly": true }'
```

```javascript Node.js theme={"dark"}
await fetch(
  `https://api.callers.ai/call/${sessionId}/warm-transfer-summary`,
  {
    method: "POST",
    headers: {
      Authorization: process.env.CALLERS_API_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ agentOnly: true }),
  }
);
```

```python Python theme={"dark"}
import os
import requests

requests.post(
    f"https://api.callers.ai/call/{session_id}/warm-transfer-summary",
    headers={"Authorization": os.environ["CALLERS_API_KEY"]},
    json={"agentOnly": True},
)
```

The endpoint works only for calls made through SIP, and only for calls whose transfer step has **Warm Transfer** on. It returns `404` if no summary exists for the session. Add the `x-sub-organization-id` header for calls in a sub-account.

## Transfer to a human operator queue

Choose the **Human operator** tab in the Call Transfer step and **Select a queue**. The call rings operators who are available in Callers, using the queue's ring strategy. With **Warm Transfer** on, the summary is delivered to the operator only.

See [Human Operators](https://docs.callers.ai/documentation/human-operators/overview.md) to create queues, set ring strategy and timeouts, and handle calls in the browser.

## SIP REFER

By default, Callers bridges the transferred call and stays on the line, which keeps recording, warm transfer, and transfer tracking working. For SIP trunks, Callers can instead hand the call to your carrier with **SIP REFER** and drop off immediately.

With SIP REFER:

* The call isn't recorded after the transfer.
* Callers can't tell whether the transfer was answered.
* Warm transfer, handoff messages, and any post-transfer logic don't run.

SIP REFER is set per SIP carrier and applies to every transfer routed through it. Contact [support@callers.ai](mailto:support@callers.ai) to turn it on.

## Recording and limits during transfers

* **Recording.** By default the recording continues after the transfer. Turn on **Stop Recording When Call Is Transferred** under **General Settings** → **Technical Settings** to stop it at the handoff. See [Call recording and limits](https://docs.callers.ai/documentation/voice/call-recording-and-limits.md).
* **Duration.** Transferred calls get an extra 150 minutes on top of the agent's maximum call duration.

## Track transfers

* The call's events and transcript show when the transfer happened.
* [Webhooks](https://docs.callers.ai/documentation/webhook/webhook-events.md) send `FORWARDED` when the call is transferred and `FORWARDED_CALL_FINISHED` when the transferred leg ends. The payload's `forwardInfo` object holds the details.
* You can get a notification when a forwarded call isn't answered. See [Notifications](https://docs.callers.ai/documentation/account/notifications.md).

## Troubleshooting

> **The transfer fails immediately**
>
> Check that the number is in E.164 format (with `+` and country code) and that your telephony provider allows calls to that destination. For contact fields, check that the variable has a value for the contact.

> **The receiver hears the summary before anyone answers**
>
> The destination is probably a queue or IVR and the summary is set to **Receiver only**. Switch to **Both parties** with **When ⁕ is pressed**, or trigger the summary with the API.

> **The contact's number isn't shown to the receiver**
>
> Your carrier may not allow caller ID that doesn't belong to your account. Use **Agent's number**, or ask your carrier to allow it.

> **The recording stops at the transfer**
>
> Check **Stop Recording When Call Is Transferred**, and whether your SIP carrier uses SIP REFER, which always ends the recording at the transfer.

## Related

> **[Human Operators](https://docs.callers.ai/documentation/human-operators/overview.md)**
>
> Queues and browser calling for your team.

> **[Steps](https://docs.callers.ai/documentation/build-your-agent/customizing-steps.md)**
>
> All step types in the script editor.

> **[Instructions and guardrails](https://docs.callers.ai/documentation/build-your-agent/instructions-and-guardrails.md)**
>
> Transfer automatically when a guardrail triggers.

> **[SIP integration](https://docs.callers.ai/documentation/integrations/sip.md)**
>
> Connect your own SIP trunk.

> **[Troubleshooting](https://docs.callers.ai/documentation/resources/troubleshooting.md#sip-and-telephony)**
>
> Transfers that fail, drop, or ring the wrong destination.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.