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

# Call Transfers

> Configure cold or warm call transfers to fixed destinations or Phone Number contact properties.

<Note>
  Warm transfers are temporarily unavailable for Duo agents. Cold transfers remain available. Saved warm-transfer destinations are skipped during calls.
</Note>

Call transfers let your AI agent hand a live call to a human. You configure one or more transfer rules per agent, and each rule can use a fixed destination or a Phone Number property from the contact. The AI decides when to use each rule based on your prompt. telli supports two types: **cold** (instant handoff) and **warm** (the AI briefs the human first).

***

## Cold vs. Warm Transfer

<Tabs>
  <Tab title="Cold Transfer">
    The caller is connected directly via SIP REFER. Fast, zero delay, and the only type that supports SIP URI targets and custom SIP headers.

    **Downside:** If the destination doesn't answer, the caller is stuck hearing ringing and the AI cannot return. No context is passed to the human.

    <Note>
      On a [custom SIP trunk](/platform/phone-numbers#connect-your-existing-number-with-sip), your provider must permit SIP REFER on the trunk. Warm transfers work without it.
    </Note>
  </Tab>

  <Tab title="Warm Transfer">
    The caller is placed on hold while the AI calls the human in a separate session, a briefing agent summarizes the conversation, and the human confirms before the caller is connected. The human gets full context, and if they decline, don't answer, or hit voicemail, the AI returns to the caller gracefully.

    **Downside:** Slower (caller on hold), and phone numbers only—no SIP URIs.
  </Tab>
</Tabs>

### When to Pick Which

| Scenario                                         | Recommended                                         |
| ------------------------------------------------ | --------------------------------------------------- |
| Transfer to a call center queue (always staffed) | **Cold**—fast, and someone will always pick up      |
| Transfer to a specific person who may be busy    | **Warm**—AI returns gracefully if they don't answer |
| You need to pass call context to the human       | **Warm**—the briefing agent summarizes everything   |
| PBX/SIP integration with custom routing          | **Cold**—supports SIP URIs and custom headers       |
| Transfer to a voicemail-heavy destination        | **Warm**—detects voicemail and returns to caller    |

***

## Warm Transfer Briefing

The briefing is what the AI tells the human before connecting the caller. In **Auto mode** (default) the AI summarizes who the caller is, what they called about, what was discussed, and what they need, then asks "Are you ready to take the call?"

You can supply a **custom briefing prompt** instead. It replaces the default instructions, but the system still appends the full conversation history, instructs the agent to ask permission before connecting, and provides the `connect_to_customer`, `wait_for_supervisor_to_return`, `voicemail_detected`, and `supervisor_unavailable` tools. Briefing prompts support contact variables like `{{contact.name}}`.

During the briefing the human can **accept** (caller connected), **ask for a moment** (the AI stays silent and checks back after 30 seconds, mentioning that the caller is still holding), **say they're unavailable** (AI returns and offers alternatives), or **not answer** (AI returns once the ring timeout expires: 5–120s when configured, 5 minutes when left empty).

***

## DTMF and SIP Headers

**Post-dial DTMF**—Send touch-tones after the destination answers, for IVR menus or extensions. Supports `0-9`, `A-D`, `*`, `#`, and `w` (0.5s pause). Example: `123w45#`. Supports contact variables (`1w{{contact.extension}}#`). Available for both cold and warm.

**Custom SIP headers (cold only)**—Attach headers to the REFER request for call correlation, routing, or analytics. telli always includes `X-Telli-Call-Id` automatically so you can match the transfer back to the original call. Add your own name/value pairs under the "Advanced" section of a cold destination; values support contact variables. Not available for warm transfers.

***

## Limited Hours

Each destination can have its own optional schedule: enable/disable per day, time windows per day, and a timezone (e.g. `Europe/Berlin`). You can also block specific dates (holidays), inheriting from account-level no-call dates or disabling per destination.

When someone requests a transfer outside the configured hours:

* **Auto (recommended)**—The AI informs the caller transfers aren't available, optionally including the schedule and next available slot. You can toggle the schedule details off.
* **Manual message**—The AI speaks an exact message you provide, verbatim, with no improvisation.

***

## Routing Logic in the Prompt

The transfer tool gives the AI the ability to transfer; your prompt tells it when. A typical multi-destination pattern:

```
## Transfer Routing

- Pricing, quotes, or purchase questions → @transferCall:sales
- Technical issues, bugs, or error messages → @transferCall:support
- Billing disputes or invoice questions → @transferCall:billing
- Explicit request for a manager → @transferCall:manager

## When NOT to Transfer
- Do not transfer if you can answer the question yourself
- Only transfer for complex issues you cannot resolve
- Always confirm with the caller before transferring
```

Common rules also include ending the call when the question is answered, using `@scheduleCallback` when the destination is unavailable, and summarizing what you've tried before transferring as a last resort.

### Route each contact to a different destination

Use a contact property when each contact needs a different transfer destination.

<Steps>
  <Step title="Create the destination property">
    Create a [contact property](../../platform/contact-properties) with the **Phone Number** type.
  </Step>

  <Step title="Set the value before the call">
    Set a valid [E.164](../../phone-number-format) value with a leading `+` for each contact. Populate it in the telli app, by CSV import, through the [Create Contact](../../v2/endpoint/create-contact) or [Update Contact](../../v2/endpoint/update-contact) API, or from the [Contact Lookup Webhook](../../contact-lookup-webhook).
  </Step>

  <Step title="Select the property">
    In the Agent Builder, open **Tools → Transfers**, select **Add transfer tool...**, and choose the property in **Transfer target**.
  </Step>

  <Step title="Test the routing">
    [Place a test call](../../en/get-started/test-your-agent) for a contact that has the property, trigger the transfer rule, and confirm that the expected destination rings.
  </Step>
</Steps>

See [Call Transfer](../../deep-dives/call-transfer#contact-specific-destinations) for runtime behavior and limitations.

***

## Troubleshooting

| Issue                          | Cold                                                                 | Warm                                                                                                  |
| ------------------------------ | -------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| **Destination doesn't answer** | Caller hears ringing indefinitely; AI cannot return (SIP limitation) | Cancels after the configured ring timeout (range 5–120s, empty means 5 minutes); AI returns to caller |
| **Voicemail on destination**   | No detection; caller connected to voicemail                          | Briefing agent detects within 10–30s and returns to caller                                            |

<Tip>
  **Recommendation:** If your destination might not answer or go to voicemail, always use warm transfer and set a reasonable max ringing duration (30–60s recommended).
</Tip>


## Related topics

- [Call Transfer](/deep-dives/call-transfer.md)
- [Phone Numbers](/platform/phone-numbers.md)
- [Changelog](/changelog.md)