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

# Call transfers

> Hand a caller to a person.

Add a transfer tool to an assistant and it can pass the caller to a human
mid-call.

There are three kinds. They differ in what the person picking up hears before
they speak to the caller.

| | The caller | The person picking up | Use it when |
| - | - | - | - |
| **Cold** | Put straight through | Gets the call, with no context | Simple routing — "put me through to sales" |
| **Warm** | Waits a moment | Hears a summary of the conversation first | The caller has already explained their problem once |
| **Warm with tools** | Waits a moment | Hears a summary that also includes data from your systems | They need the account or ticket open before they speak |

The dashboard calls the third one **Warm Transfer with Tools**; the API calls it
`rich`.

Start with warm. Move to warm-with-tools when the person answering keeps having to
look something up anyway.

<Note>
  Warm and rich call the person on your own number, so you need an outbound number
  on your [phone connection](/phone-numbers). Without one the transfer
  still goes through — it just becomes a cold transfer, so the caller reaches a
  person without the briefing.
</Note>

## Setting one up

Create a transfer tool under **Tools** and attach it to an assistant.

| Field | What it does |
| - | - |
| **Mode** | Cold, warm, or warm with tools. |
| **Destination** | Where the call goes — a phone number like `+4930111111`, a SIP address, or an extension. |
| **Allowed destinations** | A list to choose from, when you want the assistant to pick. |
| **On fail** | Hand the caller back to the assistant, or end the call. Defaults to handing back. |
| **Prompt** | The situations that should trigger it. This is what the assistant reads when deciding. |
| **Summary instruction** | For warm transfers: what the briefing should cover. |

Destinations ring for 30 seconds before giving up. That's adjustable over the API
but not in the dashboard.

### One destination, or several

Set a **destination** and every transfer goes there.

Leave it empty and fill in **allowed destinations** instead, and the assistant
chooses — billing, or technical support, or the shift manager. It can only pick
from that list, so it can't dial a number you didn't put there.

## What the caller hears

Just before handing over, the assistant tells the caller what's happening — naming
where they're going, in the language it's been speaking.

You don't write this line. The assistant knows what a fixed sentence can't: who
the caller is being put through to, and what they asked for a moment ago. It waits
for the sentence to finish before transferring, so nobody is cut off mid-word.

## When a transfer doesn't work

A transfer can fail because the line is busy, nobody answers in time, the person
declines, or it reaches voicemail.

By default the caller stays with your assistant, and the assistant is told which
of those happened. That matters: "the line is busy" and "nobody picked up" lead to
different things to say. It can offer to take a message, try another department,
or explain the wait.

Set **if the transfer fails** to end the call instead, and it apologises and hangs
up.

## What the briefing says

For a warm transfer, the assistant writes a short handoff summary and speaks it to
the person picking up. **Summary instruction** is what shapes it. The default asks
for the caller's latest request, the important context, and anything already done.

Change it to match what your team needs to hear first:

```text theme={null}
Lead with the account number and the reason for the call. Then say what has
already been tried. Keep it under fifteen seconds.
```

## Adding data to the briefing

**Warm with tools** runs one or more of your [tools](/tools) before writing the
summary, so it can include a ticket, an order or an account record.

Add them as **transfer context tools** on the transfer. They only run at transfer
time — the assistant can't call them during the conversation — so a slow lookup
that would be awkward mid-call is fine here.

If one fails, the transfer still goes ahead with a shorter summary.

## Seeing transfers

A transfer appears in the [call](/calls) transcript like any other tool.

To act on one in your own systems, subscribe to the
[`call.transferred` webhook](/api-reference/webhooks/call-transferred). It tells
you the type, the destination, and whether it worked.

## Technical note

A cold transfer is a SIP REFER — once it completes, the caller is on your
carrier's leg and Qall is out of the call. A warm or rich transfer keeps the call
on Qall, dials the person on your outbound number, and merges them in. That's why
only warm and rich can brief anyone, and why they need an outbound number.


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