Transfers, Forwarding and the Duty Roster

Warm transfers that brief the human first, cold transfers, conditional forwarding numbers, and routing to whoever is on duty.

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.

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.

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), 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").

Click Add Forwarder.
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.
Add a row per destination. Use Remove to delete one.
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.

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.

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.

Transfers, Forwarding and the Duty Roster