# Source: https://docs.ultravox.ai/telephony/call-transfers.md

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

# Call Transfers

> Transfer calls between AI agents and human operators.

Call transfers allow your AI agents to seamlessly hand off conversations to human operators when needed. This is essential for scenarios where the AI agent cannot resolve a customer's issue, needs to escalate to a specialist, or when the caller specifically requests to speak with a human.

## Understanding Call Transfers

Call transfers work by providing your AI agent with a custom tool that enables it to transfer active calls to human operators. The agent uses this tool based on instructions in your system prompt and the tool's description, determining when and how to initiate transfers.

<Note>
  <b>Agent-Initiated Transfers</b>

  The AI agent decides when to transfer calls based on your instructions. You control this behavior through your system prompt and tool configuration.
</Note>

### Transfer Variants

There are two main types of call transfers you can implement:

**Cold Transfer** → The call is immediately transferred to the human operator without any preparation or context sharing. Also known as a blind transfer or unattended transfer.

**Warm Transfer** → The agent provides context about the conversation to the human operator before the caller is connected. Also known as an attended transfer or whisper transfer.

Additionally, there are two methods by which a transfer may be implemented:

**Refer** → The SIP REFER verb is used to connect the caller with the human operator, removing the agent and related SIP stack altogether. This is almost always preferable as long as all the relevant SIP providers support it.

**Bridge** → The human operator is dialed using a second SIP INVITE. While the agent leaves the call, the SIP stack remains and bridges audio between the caller and the human operator. This is less efficient and will incur additional costs, but may be necessary if your SIP provider does not support REFER transfers.

<Note>
  <b>Bridge Transfers Cost More</b>

  Using bridge transfers will result in SIP charges beyond the Ultravox call duration as our SIP infrastructure remains active to bridge audio between the caller and human operator.
</Note>

## SIP Call Transfers

For SIP calls, transfers can be achieved using built-in tools for [cold transfers](/tools/built-in-tools#coldtransfer) or [warm transfers](/tools/built-in-tools#warmtransfer).

### Cold Transfers

Cold transfer uses refer transfers by default. If you need to use bridge transfers instead, you can override the `sipVerb` parameter from `REFER` to `INVITE` when adding the tool to your agent (or call). You may also wish to set `from`, `username`, and/or `password` in order to authenticate the subsequent INVITE. The `from` parameter defaults to the user's sip address if not specified.

Should the transfer fail (e.g., the human operator declines the call or otherwise fails to answer), the caller will be returned to the AI agent to continue the conversation. Transfers may be retried by the agent as needed.

### Warm Transfers

When an agent begins a warm transfer, a second SIP call is created to connect the agent with a human operator. This always happens with an INVITE, so you likely want to set `from`, `username`, and `password` parameter overrides in addition to the required `target` parameter override. As with `coldTransfer`, the `from` parameter defaults to the user's sip address if not specified.

When the human operator answers, they speak with the agent to receive context about the caller and reason for the transfer. They may accept or reject the transfer using natural conversation. If they reject the transfer, the agent reconnects with the original caller and explains that the transfer was rejected, offering a reason if provided by the human operator.

If the human operator accepts the transfer, the human operator and original caller are connected and the agent leaves the call.  By default the connection happens using an in-session REFER while falling back on bridging the calls if the REFER fails. You can override this behavior by setting the `transferType` parameter to either `REFER` or `BRIDGE` to force a specific transfer method. (The default is called `TRY_REFER`.)

## Call Transfers with Other Telephony Providers

<Info>
  <b>Built-in coldTransfer tool with Twilio</b>

  <br />

  The built-in `coldTransfer` tool also works with Twilio if you've [added your credentials](/telephony/supported-providers#providing-telephony-credentials), but be aware that invoking the tool will immediately end the Ultravox call regardless of whether the transfer succeeds.
</Info>

To implement call transfers:

<Steps>
  <Step title="Create a Transfer Tool">
    Build a custom tool that your AI agent can call to initiate transfers. This tool should handle the telephony provider's transfer APIs.
  </Step>

  <Step title="Configure Agent Instructions">
    Update your system prompt to instruct the agent when and how to use the transfer tool. Include guidelines for all transfer scenarios and when transfers should occur (e.g., "Transfer when you cannot answer billing questions" or "Transfer if the customer asks for a manager").

    Instruct your agent to politely explain the transfer to the customer before initiating it (e.g., "I'm going to connect you with a specialist who can better help with your billing question").
  </Step>

  <Step title="Handle Transfer Logic">
    Implement the backend logic to manage the actual call transfer using your telephony provider's APIs.
  </Step>
</Steps>

```js Example Call Transfer Tool Definition theme={null}
{
  "toolName": "transferCall",
  "description": "Transfer the current call to a human agent when you cannot resolve the customer's issue or when they specifically request to speak with a human.",
  "parameters": {
    "destinationNumber": {
      "type": "string",
      "description": "The phone number to transfer the call to"
    },
    "transferReason": {
      "type": "string",
      "description": "Brief explanation of why the call is being transferred"
    }
  }
}
```

### Twilio

Twilio supports both blind and attended transfers through different APIs. Blind transfers use the simple `<Dial>` verb to immediately connect the caller to a new destination, while attended transfers utilize Twilio's Conference API to create a three-way call before the agent disconnects.

**Blind Transfer**: Uses Twilio's `calls.update()` method with TwiML containing a `<Dial>` verb to immediately redirect the call.

**Attended Transfer**: Creates a conference call, places the original caller on hold, calls the human agent with a whisper message, and allows the agent to join the conference after hearing the context.

The attended transfer process involves:

1. Putting the caller on hold with music
2. Creating a conference call
3. Calling the human agent with the transfer reason
4. Requiring the agent to press a key to join
5. Connecting all parties to the conference
6. Allowing the AI agent to disconnect

<Tip>
  <b>Complete Example Available</b>

  We have a full working example of Twilio call transfers (including both blind and attended transfers) available in the [`ultravox-examples`](https://github.com/fixie-ai/ultravox-examples/tree/main/telephony/twilio-call-transfer-ts) repo.
</Tip>

## Conclusion

Call transfers are essential for creating robust AI-powered voice applications that can seamlessly escalate to human operators when needed. By implementing both blind and attended transfer capabilities, you can ensure customers receive the appropriate level of service while maintaining a smooth experience throughout the conversation.