# Transfers, Forwarding and the Duty Roster

Sooner or later a caller needs a person. A voice agent can hand the call over
in two ways, choose between several destinations based on what the call turned
out to be about, and — if you use the duty roster — reach whoever is actually
working right now instead of a number that was right when the agent was built.

## What you'll need

- The **`agents:voice:manage`** permission.
- A saved voice agent on **Telephony** delivery.
- The numbers you want to forward to. Any reachable phone number works; they
  do not have to be numbers you provisioned in Karmaflow.ai.
- For duty-roster routing, a configured duty schedule — see
  [Duty Schedule](/help/duty-schedule/voice-agent-tools).

## Warm and cold transfers

Both are tools you enable on the **Tools** tab. The agent decides which to use
from your instructions, so enable the one you want it to use — or both, and
tell it when each applies.

```mermaid
sequenceDiagram
    participant C as Caller
    participant A as Voice agent
    participant H as Your team member
    Note over C,A: Warm transfer
    A->>C: "Let me get someone — one moment"
    A->>C: Hold music
    A->>H: Dials, then briefs: who is waiting and why
    A->>C: Bridges caller and human
    Note over C,A: Cold transfer
    A->>C: "I'm putting you through now"
    A->>H: Forwards immediately, agent leaves
```

**Warm transfer** (`transfer_call`) puts the caller on hold with music (which
music is yours to choose — see [Hold music](#hold-music)), calls the human, tells them who is waiting and what the call is about, and only then
connects the two. The human walks into a conversation already in progress
instead of starting over. If the destination does not answer, or answers with
voicemail, the agent falls back to the next destination rather than dumping
the caller. A warm transfer that has not connected after 5 minutes (the line
rings on, an automated menu answers, or the person never says yes or no)
ends, and the agent is back with the caller to offer the next step.

Use it for anything where context matters — support escalations, a qualified
lead, a complaint, anything the caller has already explained once.

**Cold transfer** (`cold_transfer`) forwards immediately and leaves. Faster,
no hold music, no briefing.

Use it when the destination does not need context: a main switchboard, a
department that will ask its own questions, a caller who explicitly asked for
extension 204.

Both tools exist so the agent can pick. Say in your instructions which
situations call for which — "warm transfer anything a customer has already
described; cold transfer a caller who asks for a specific person by name" is a
good default.

## Set up forwarding destinations

**Telephony** tab → **Call Forwarding** ("Specify forwarders for conditional
call routing").

1. Click **Add Forwarder**.
2. Fill the row:
   - **Forward Number** — the number to dial: `+`, the country code, then the
     number (`+1xxxxxxxxxx`). Spaces, dashes and brackets are fine, and the
     number is saved in that compact form; one without `+` gets your workspace's
     default country code. Extensions can't be dialled on a transfer, so
     enter the main number.
   - **Condition** — plain English describing when this destination is the
     right one. The agent reads these and chooses.
3. Add a row per destination. Use **Remove** to delete one.
4. **Save Changes**. A number that can't be dialled — a missing digit, a stray
   bracket, an extension — is shown in red under its row as you type, and the
   save is refused with the row named and the fix spelled out — for example
   *Transfer number 1 (Billing, invoices, refunds, payment…): The brackets in
   "+1xxx)xxxxxxx" do not pair up. Did you mean +1xxxxxxxxxx?* The agent's
   page shows the same warning on a number saved before this check existed.

The **Condition** field is the part that decides whether this works. Write
conditions that are mutually exclusive and phrased the way your instructions
phrase the same situations:

| Forward Number | Condition |
|---|---|
| +1 (xxx) xxx-xxxx | Billing, invoices, refunds, payment problems |
| +1 (xxx) xxx-xxxx | Technical faults where the customer has already tried the basic steps |
| +1 (xxx) xxx-xxxx | Anything else, or the caller asks for a person without saying why |

Avoid conditions that overlap ("urgent issues" and "technical issues" will
both match the same call) and avoid conditions that depend on information the
agent has no way to know.

**Always include a catch-all row.** A caller who needs a human and matches
none of your conditions is the worst outcome on this page.

## Route to whoever is on duty

**Telephony** tab → **Call Forwarding** → **Use On-Duty Roster for
Transfers** (off by default).

When it is on, the people currently on duty — those whose duty record allows
accepting transfers — are tried **ahead of** the forwarders below, and the
agent is given the cascade rules for working down the list. Your forwarders
stay as the fallback.

Turn it on when who answers depends on the day or the shift, and off when a
destination is a department rather than a person.

It requires a configured duty schedule: **Agents → Workflows → Duty
Schedule**. With nothing scheduled, the switch has nothing to route to and the
agent falls through to the forwarders.

### Related duty tools

Two more tools on the **Tools** tab work with the same schedule and are worth
enabling together:

- **`duty-check`** — looks up who is on duty, so the agent can *tell* the
  caller who will call them back, or decide whether escalating is even
  possible right now.
- **`duty_notify`** / **`duty-notify-confirm`** — email and text the on-duty
  person about this call, with a fallback to the configured default contact.
  This is the answer to "nobody can take the call right now": the agent takes
  the details and the right person is notified rather than the caller being
  told to try later.

Full reference: [Duty Schedule — Voice Agent Tools](/help/duty-schedule/voice-agent-tools).

## Write the instructions for a transfer

The tools and the numbers are the easy half. What decides whether transfers
feel good is the instructions:

- **Say when to try and when not to.** Without a rule, agents either transfer
  at the first sign of difficulty or never transfer at all.
- **Say what to tell the human.** The briefing is generated — tell it what
  matters: the caller's name, the account, what they have already tried, what
  they want.
- **Say what to do if nobody answers.** Take a message and notify with
  `duty_notify`? Offer a callback? Both? The fallback should be your decision,
  not an improvisation.
- **Say what to tell the caller while they wait.** Silence plus hold music
  with no explanation is where callers hang up.

## What the agent says around a transfer

Two moments in a transfer used to be fixed platform sentences. Both are now the agent's by default, and yours by choice, on the **Voice** tab's **What the agent says at fixed moments** card:

| Moment | Agent decides (default) | Exact line |
|---|---|---|
| **When a transfer connects** | As the colleague joins, the agent hands the caller over in one sentence that names them, then leaves the line. | Your words, spoken verbatim. Blank uses "You are now connected. I'll be hanging up now." |
| **When a transfer does not connect** | Nothing fixed is said. The agent is told what happened (voicemail, with or without a message left; declined; an error) and tells the caller in its own words, then offers the next step: another person, a callback, or taking a message. | Your words first, then the agent continues. Blank uses "I'm sorry, I couldn't reach them right now." |

Pick **Exact line** when a regulator, a brand guide or a client script requires specific words. Otherwise leave **Agent decides**: it answers in the caller's language and fits the sentence to the call.

## Hold music

During a warm transfer the caller hears hold music from the moment the agent
starts the transfer, through the ringing and the whole briefing, until they are
connected or the agent comes back to them. Their microphone is off for that
time. A cold transfer has no hold: the caller goes straight to the other line.

Every agent plays **Classic hold** until you choose otherwise. To choose, a
tenant admin opens **Settings (gear) → Channels → Hold Music**:

- **Karmaflow catalog** — tracks Karmaflow makes available, grouped by theme
  (seasonal and holiday music is added as it arrives). **Add to library** puts
  one in your library; nothing plays on a call until you choose it.
- **Upload your own** — an MP3, WAV or OGG file of 10 seconds to 10 minutes,
  up to 15 MB. It counts towards your workspace's storage.
- **Your library** — every track you added or uploaded, with **Play**, a
  **Volume** slider and **Pause**. A paused track stops playing everywhere
  without changing any agent: agents that use it play the default instead
  (or Classic hold if the default is the paused one) until you resume it.
- **Default for voice agents** — the track every agent plays unless you choose
  one on the agent itself.

To give one agent its own track, open the agent, go to the **Telephony** tab,
and pick it under **Call Forwarding → Hold music**. Like every agent setting,
the new track reaches live calls when you **Push Live**; until then the
agent's page shows both what live calls hear and what the draft will play. It
also says when a track can't play (paused, removed, or retired from the
catalog), why, and what plays instead. The call record says the same for each
transfer.

**Your rights to the audio.** You must own the audio you upload or hold a
licence that lets you play it to callers. Music played on hold is a public
performance: commercial recordings usually need a music-on-hold licence (in
Canada from SOCAN and Re:Sound), and you are responsible for having it. Every
upload asks you to confirm this.

**Getting it to sound right.** Phone lines carry a narrow band of sound, so
full mixes sound thin and simple instrumental tracks work best. Keep the volume
steady, avoid speech that could sound like someone answering, and avoid
silence at the start or end. The track loops for as long as the transfer takes,
so 1 to 5 minutes is a good length. Turn on **Phone line** on the Hold Music page
to hear a track roughly as a caller will.

## Reaching an extension or getting through a menu

If a destination is behind an IVR or an extension, enable **`send-dtmf`** on
the **Tools** tab — it lets the agent press keypad tones to navigate a menu or
dial an extension. Outbound calls can also dial an extension automatically
after the callee answers. See
[Placing Outbound Calls](/help/voice-agents/campaign-usage).

## Live-audio agents and transfers

On a **Gemini 3.8 Live** agent the warm transfer works as described above,
with one difference the call page shows: the agent keeps the whole
conversation while it hands the caller over and picks it back up if the
colleague does not take the call (Google holds that conversation for two
hours from the hand-over, far longer than any transfer takes). The colleague's
leg — the agent's brief to your teammate — runs on the normal pipeline. The
**fixed moments** around a transfer are always the agent's own words on a
live-audio agent; an **Exact line** saved earlier is read as a direction.
Under **Tools → Tools on live-audio calls**, `transfer_call` and `end_call`
default to **Wait for the result**, because the call cannot continue past them.

## Troubleshooting

- **The agent never transfers.** Check `transfer_call` (or `cold_transfer`) is
  ticked on the **Tools** tab, that at least one forwarder exists, and that
  the instructions actually tell the agent to use it.
- **It transfers to the wrong person.** The conditions overlap or are too
  vague. Rewrite them so exactly one matches any given call, and mirror the
  same wording in the instructions.
- **The human gets no briefing.** That is a cold transfer. Warm transfers
  brief; enable `transfer_call` and say which situations warrant it.
- **The caller is dropped when nobody answers.** Add a catch-all forwarder, and
  say in the instructions what to do when a transfer fails.
- **The on-duty switch is on but calls go to the forwarders.** Nobody is
  scheduled right now, or the scheduled person's record does not allow
  transfers. Check **Agents → Workflows → Duty Schedule**.
- **Transfers work in the browser test but not on the phone.** Telephony-only
  behaviour — transfers, voicemail detection and caller-ID lookup — is not
  part of a browser test, and the panel says so. Use **Simulate Call**.

## Next steps

- [Tools, Knowledge and Memory](/help/voice-agents/tools-and-knowledge)
- [Placing Outbound Calls](/help/voice-agents/campaign-usage)
- [Duty Schedule — Voice Agent Tools](/help/duty-schedule/voice-agent-tools)
- [Phone System Integration (PBX / 3CX)](/help/voice-agents/phone-system-integration)