Call Transfer Tool

The Call Transfer tool performs a blind transfer during a live call. When the LLM decides a transfer is needed (based on the tool's description and conversation context), the platform initiates the transfer to the configured destination and disconnects the AI from the call.

How It Works

Supported Telephony Providers

Call transfer support depends on the telephony provider handling the call:

Configuration Reference

Common Fields

Example description:

Use this tool when the caller asks to speak with a human agent, requests to be transferred, or when you cannot resolve their issue and they need human assistance.

Transfer Destination

The destination supports two formats:

You can toggle between phone number and SIP mode in the dashboard using the link below the destination input.

Pre-Transfer Message

Controls what happens before the transfer is initiated.

Message Options

Transfer Timeout

If the destination does not answer within the timeout, the behavior depends on the telephony provider:

Tool Definition Schema

The full JSON schema for a Call Transfer tool definition:

{
  "schema_version": 1,
  "type": "transferCall",
  "config": {
    "destination": "+14155551234",
    "messageType": "custom",
    "customMessage": "Please hold while I transfer your call to our support team.",
    "audioRecordingId": null,
    "timeout": 30
  }
}

Example: Transfer to Support Team

Configuration:

• Name: Transfer to Support
• Description: Use this tool when the caller asks to speak with a human agent, requests to be transferred to support, or when you cannot resolve their issue.
• Destination: +18005551234
• Message Type: Custom
• Custom Message: I'm transferring you to our support team now. Please hold for a moment.
• Timeout: 30 seconds

What happens during a call:

1. Caller: "I'd like to speak with someone about my billing issue."
2. LLM recognizes the transfer intent and triggers the tool.
3. Agent says: "I'm transferring you to our support team now. Please hold for a moment."
4. The platform initiates a blind transfer to +18005551234.
5. The AI disconnects. The caller hears ringing and is connected to the support team.

What Happens After the Transfer

The platform waits for the destination to actually answer before letting go of the call:

• The AI agent stays on the line while the destination's phone is ringing. The pipeline does not end until the destination picks up — so a no-answer or busy doesn't kill the original call mid-ring.
• The caller hears ringing as the transfer destination's phone rings — the platform's hold music where the caller stays on our stream (Twilio, Telnyx, Vonage, ARI), or carrier-delivered hold/ringback for redirect-style providers (Vobiz, Plivo, Cloudonix, Smartflo).
• If the destination answers, the bridge is set up provider-side (conference for Twilio, linked dial for Telnyx, conversation for Vonage, A-leg redirect for Vobiz/Plivo), the agent's pipeline closes cleanly, and the caller is now connected directly. This is a normal phone call between the caller and the destination.
• If the destination does not answer (busy, no-answer, failed, timed out), the agent does not drop the call. Instead the LLM is told the transfer failed and can verbalize the outcome — "Sorry, no one picked up. Is there anything else I can help with?" — so the conversation continues.
• The call record is updated with the transfer event, including the destination number, timestamp, and the result.

Recording the Transfer

Two flags decide what gets captured on the carrier's side. Both default to a sensible value, so you don't have to set them unless you want to override. The transfer tool's Record Transferred Call toggle in the dashboard maps to recordTransfer.

With both defaults untouched, a transfer is tail-recorded out of the box: recordInProviderConsole defaults off and recordTransfer defaults on, so an API caller who never mentions either flag gets the transferred conversation recorded and attached to the call automatically.

Automatic download to the call record

When a transfer-leg recording is captured, the platform fetches it from the carrier after the transferred conversation ends and stores it with the call:

1. At transfer time the call row records the transfer correlation (transfer_id, provider, destination, B-leg ID).
2. When the carrier signals the recording is ready (Twilio's conference recordingStatusCallback, Vobiz/Plivo <Record> completion callbacks, Telnyx's call.recording.saved event, Vonage's record event, Cloudonix's Dial recording callback, ARI teardown, Smartflo CDR), a background job downloads the media with the call's own provider credentials.
3. The file is re-hosted in platform storage and appended to the call's recordings as a kind: "transfer" entry.
4. The call detail page then shows a second player — Transferred Call Recording — below the main one, with its own playback-speed control and download. The GET /calls/{callId} response includes the entry (as a signed URL) only when the recording exists.
5. If the call has a webhook configured, a call.transfer_recording.completed event fires with the recording link and the same callId as the earlier lifecycle events — so your receiver can attach the late artifact to the right call.

Because the transferred conversation can continue long after the agent leaves the call, the transfer recording typically appears in call history minutes after the main recording. If the carrier never produces a file (for example the transfer was too short) or the file can't be downloaded, the entry never appears — and a configured webhook receives call.transfer_recording.failed with the reason instead.

Cascade

What the caller hears while the destination rings

After the optional pre-transfer message, the caller hears the platform's hold music until the destination answers, rejects, or the transfer times out — at which point the music stops immediately (they're either bridged to the human, or the agent comes back to explain the failure). The agent does not hear the caller during this window (user input is muted for the duration of the transfer attempt).

How the hold music is delivered depends on the provider:

Pre-answer ring audio

No provider's transfer recording captures the pre-answer ring audio on the transfer leg — recording starts the instant the destination picks up. The "from ringing" you might see in other platforms typically refers to Twilio's machine-detection feature, not to ring-back capture.

Provider support matrix

The two flags above only do something when the underlying telephony provider supports the relevant primitive. Use this table to set realistic expectations per provider.

Where full-call carrier recording is marked Not available (Vonage, Cloudonix), setting recordInProviderConsole=true is logged as "skipped" by the runner and the call proceeds normally — the flag is harmless, just inactive. zoxa's own S3 recording is independent of all of this and continues to work on every provider.

What gets captured per cascade row (provider-aware)

Combining the cascade with the provider matrix, the practical outcomes per provider:

• Twilio, Vobiz, Plivo, Telnyx: full cascade behavior — both flags do exactly what they describe, and the transfer-leg file is auto-attached to the call record.
• Vonage, Cloudonix: recordTransfer works and the file is auto-attached; recordInProviderConsole (full-call carrier recording) is not available, so zoxa's S3 recording is the only full-call copy.
• ARI: recordInProviderConsole=true records the user's channel only (Asterisk's note about channel vs bridge); the transfer leg, however, is recorded properly as mixed bridge audio when recordTransfer is on.
• Smartflo: recording is controlled on the Tata side (account/route settings), not per call. With recordTransfer on, the platform fetches the CDR recording after the call — note it spans the whole call (initial leg + first transfer), since that is how Tata records.

Where to find the recording

The transferred-call recording appears on the call detail page as a second player under the main recording, once the background fetch completes. The carrier-side IDs remain visible in the tool-call Outcome block on the Transcript tab:

• Transfer SID → the transfer leg's carrier ID (Twilio B-leg CallSid / Vobiz BLegCallUUID), useful for cross-referencing in the carrier console.
• Original SID → the original caller's leg, useful when recordInProviderConsole is true (the full-call recording is indexed by this).

Transfer Outcome Reasons

Every transfer ends with one of the following reason values inside the transferCall tool result. The same value is emitted on the call.completed webhook's tool entry. Two categories — carrier-reported outcomes and tool-side errors — with different semantics.

Carrier-reported outcomes

These mean the transfer attempt ran end-to-end and the telephony provider reported a definitive result. The tool itself succeeded; the destination just didn't get bridged. Use these to drive your post-transfer business logic (retry, queue, voicemail fallback, etc.).

All four use Twilio's canonical spelling (no-answer with hyphen, canceled with one L) so a single parser handles both providers. The accompanying transfer_call_sid lets you cross-reference the carrier's console.

Tool-side errors

These indicate the transfer attempt never completed. Either the platform refused to dial, the provider rejected our request, or the carrier never reported back. Treat them as bugs to triage, not customer-facing outcomes.

Status interpretation

• result.status === "success" plus action: "destination_answered" — the destination picked up. The agent's pipeline is closing; the caller is now in the human conversation.
• result.status === "transfer_failed" plus any of the carrier-reported reasons above — the tool succeeded but the bridge didn't form. The agent continues; the LLM verbalizes the outcome to the caller.
• result.status === "transfer_failed" plus a tool-side error reason — the tool itself failed. The agent continues; treat as an internal alert.

Best Practices

1. Write clear trigger descriptions -- the LLM decides when to transfer based on the description. Be explicit about what phrases or scenarios should trigger a transfer.
2. Always use a pre-transfer message -- even a simple "Please hold while I transfer your call" prevents the caller from experiencing unexpected silence.
3. Set appropriate timeouts -- 30 seconds is usually sufficient. Increase for call centers with longer queue times.
4. Use E.164 format -- always include the country code with a + prefix. Never use local number formats.
5. Test the destination number -- verify the number is correct and reachable before deploying the tool to production.