> ## 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 Transfer

> How cold and warm transfers use 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 transfer allows your AI agent to hand off conversations to human team members when needed. telli supports two transfer methods: cold transfer (immediate) and warm transfer (briefed).

## Cold Transfer

Immediately connects the caller to the destination number without any briefing.

**How it works:**

1. AI informs caller they're being transferred
2. Call connects directly to destination
3. AI disconnects immediately

<Warning>
  If the destination doesn't answer, the caller will hear ringing indefinitely.
  The AI agent cannot return to help.
</Warning>

<Info>
  **Technical detail:** Cold transfers use the SIP REFER method. For every cold
  transfer, telli includes `X-Telli-Call-Id` in the SIP REFER request headers,
  with the telli call id as its value for downstream call correlation.
</Info>

***

## Warm Transfer

Places caller on hold while the AI briefs the human agent before connecting them.

**How it works:**

1. AI places caller on hold with music
2. AI calls destination in a separate session
3. AI summarizes the conversation for the human agent
4. Human agent accepts or declines the transfer
5. If accepted: caller connects to the briefed agent
6. If declined/unavailable: AI returns to caller with explanation

**Key advantages:**

* Human receives conversation summary before speaking to customer
* Automatic detection of voicemail or unavailability
* AI can resume conversation if transfer fails
* Better customer experience with informed handoff

### Timeout Handling

| Scenario               | Detection Time | Result                 |
| ---------------------- | -------------- | ---------------------- |
| No answer              | 5 minutes max  | AI returns to caller   |
| Voicemail detected     | 10-30 seconds  | AI returns immediately |
| Agent says unavailable | Immediate      | AI returns immediately |
| Caller hangs up        | Immediate      | Transfer cancelled     |

***

## Configure a transfer destination

In the Agent Builder, open **Tools → Transfers** and select **Add transfer tool...**.

Configure these fields:

* **Label**: Internal name (for example, `sales` or `support`)
* **Transfer target**: A fixed phone number or a Phone Number contact property
* **Description**: When the agent should use this destination
* **Transfer type**: Cold or warm

Warm transfers add two optional limits:

* **Ring timeout (seconds)**: Cancel the transfer when the destination does not answer within 5–120 seconds. Leave it empty to let the destination ring for up to 5 minutes.
* **Max transfer attempts**: Refuse further attempts to this destination after 1–10 dials within the same call. Leave it empty to let the agent decide based on the conversation.

Phone-number targets must use [E.164 format](../phone-number-format) with a leading `+` (for example, `+4917612345678`). Cold transfers also accept `tel:` and `sip:` URIs. Warm transfers accept phone numbers and `tel:` URIs.

<Note>
  You can add multiple transfer destinations. The AI will choose based on
  conversation context.
</Note>

## Contact-specific destinations

A transfer target can use a **Phone Number** [contact property](../platform/contact-properties) instead of a fixed number. This lets the same transfer configuration route each contact to a different destination.

When the call starts, telli replaces the property reference with that contact's value and normalizes valid formatted phone numbers. Changes during the call affect only later calls.

If the property is empty or does not contain a valid phone number, the call still starts. The transfer tool returns an error only if the agent tries to use that destination.

See [Route each contact to a different destination](../cookbooks/call-transfers/overview#route-each-contact-to-a-different-destination) for setup instructions.


## Related topics

- [Call Transfers](/cookbooks/call-transfers/overview.md)
- [Phone Numbers](/platform/phone-numbers.md)
- [Changelog](/changelog.md)