Transfer Live calls to human agents with Bolna voice AI

What is call transfer?

Call transfer enables your Voice AI agent to route live calls to human agents, specific phone numbers, or your own SIP trunk based on conversation context. Essential for escalations, specialized support, or when human intervention is needed.

Configuration options

Transfer call configuration dialog with a Description (Prompt) box, a Transfer destination choice of Phone number or SIP trunk (URI), a Transfer to phone number field, a Pre-tool message with Hindi and English tabs, a Send a pre-call webhook before transfer toggle and a Save transfer call button — Transfer Call Configuration Modal

Setting	Description
Description (Prompt)	Tell the LLM when to trigger the transfer. Be specific - e.g., “Transfer when caller requests to speak with a human agent or sales team.”
Transfer destination	A phone number in international format (e.g., `+19876543210`), or a SIP URI pointing at your own trunk (e.g., `sip:1234@sbc.example.com`). See Transfer to a SIP trunk.
Pre-tool message	What the agent says while transferring - e.g., “Sure, I’ll transfer the call for you. Please wait a moment.” Supports multiple languages.
Pre-call webhook	Optionally notify a URL of your choice before the transfer happens — useful for sending the transfer reason to your system in real time. See Pre-call Webhook.

The pre-tool message has one tab per language configured on the agent’s Languages tab, so multilingual callers hear the handoff in their own language.

Transfer to a SIP trunk

An agent on Plivo telephony or on a SIP trunk can transfer a call straight to a SIP URI instead of a phone number. Set the destination to a SIP URI and the call is delivered to that address.

{
  "call_transfer_number": "sip:1234@sbc.example.com"
}

SIP URI transfer is available on Plivo telephony and on SIP trunks. On an agent using any other telephony provider, a transfer tool with a SIP URI destination does not fire, and the agent dashboard marks the tool accordingly. On a SIP trunk the transfer leaves through the same trunk, so a SIP URI must use the sip: scheme and point at one of that trunk’s gateway hosts. A URI for any other host is refused. See Transfer calls on a SIP trunk.

Custom SIP headers

Alongside the destination, a transfer tool can carry custom SIP headers. Each header is delivered on the outgoing INVITE with the name exactly as you write it, which lets your trunk route or annotate the call.

{
  "call_transfer_number": "sip:1234@sbc.example.com",
  "sip_headers": {
    "AccountId": "48219",
    "Segment": "gold",
    "OrderId": "%(order_id)s"
  }
}

Header values support the same %(field)s substitution syntax used elsewhere, resolved from the variables you pass when placing the call. A variable the call does not supply resolves to an empty string, so pass every variable your headers reference. Headers must satisfy the following rules, which differ by telephony:

Rule	Plivo	SIP trunk
Name characters	Letters and digits only	Letters, digits and hyphens
Name length	24 characters at most	64 characters at most
Value characters	Any character except a comma or an equals sign	Any character except a quote (`'` or `"`), `\|`, `{`, `}`, `\` or a control character
Value length	120 characters at most	120 characters at most

On Plivo, any header that breaks a rule is left off the INVITE. On a SIP trunk, a header whose name or value characters break a rule is rejected when you save the agent, as is a reserved name (X-Bolna-*, X-Trunk, X-Client-Call-ID) or a header the SIP stack sets itself, such as From, To, P-Asserted-Identity or Diversion; a value longer than 120 characters after substitution is left off. On both, a header whose value resolves to empty is left off.

Header values are delivered exactly as written, with no encoding applied, so your trunk reads them verbatim.

UI configuration

In the agent dashboard, the Transfer Call configuration modal offers a Transfer destination choice between a phone number and a SIP trunk URI when the agent runs on Plivo telephony or a SIP trunk. Choosing SIP trunk (URI) reveals the URI field and a Custom SIP headers list where each row is a header name and value. Values accept %(field)s placeholders, and a picker inserts the variables your agent already references.

Transfer calls on a SIP trunk

On a call that arrived on or was placed through your SIP trunk, Bolna dials the transfer target through the same trunk and bridges the caller to it when it answers:

A phone number destination is dialled through your carrier, with your trunk number on the call as the caller ID.
The caller hears ringback while the target rings, for 30 seconds by default.
If the target is busy, does not answer or rejects the call, the call ends.
The transfer takes a second channel on the trunk while it is live, so it is refused when the trunk has no free channel.

See Transfer calls on a SIP trunk for the full behaviour and the headers sent on the transfer leg.

Pre-call webhook

The Transfer Call tool can fire an optional pre-call webhook — a notification sent to a URL of your choice before the call is transferred. A common use case is sending the transfer reason to your system so a human agent has context the moment the call connects.

The pre-call webhook is fire-and-forget. A slow or failing webhook endpoint never blocks or delays the transfer itself.

Two optional fields control the webhook:

Field	Purpose
`pre_call_webhook_param`	The JSON body template to send, with `%(field)s` substitution. This is the on/off switch — if it is not set, no pre-call webhook fires.
`pre_call_webhook_url`	Where to send the webhook. If left blank, the agent-level Webhook URL is used instead.

Available substitution fields

pre_call_webhook_param is a JSON template. You can reference the transfer tool’s runtime arguments using the same %(field)s substitution syntax used elsewhere. The Transfer Call tool exposes:

Field	Description
`%(reason)s`	Why the caller is being transferred, as determined by the LLM.
`%(summary)s`	A short summary of the conversation so far.
`%(call_transfer_number)s`	The destination number the call is being transferred to.
`%(call_sid)s`	The telephony provider’s call identifier.

Any field that is not available at transfer time is sent as an empty string rather than failing the substitution.

{
  "pre_call_webhook_url": "https://your-api.com/pre-transfer-hook",
  "pre_call_webhook_param": {
    "transfer_reason": "%(reason)s",
    "conversation_summary": "%(summary)s",
    "transferred_to": "%(call_transfer_number)s",
    "channel": "voice"
  }
}

Static values (like "channel": "voice" above) are passed through as-is; %(field)s placeholders are substituted with the transfer tool’s runtime arguments.

What your endpoint receives

The webhook body is the same execution record you receive on the post-call execution webhook (execution id, agent id, telephony details, status, etc.), merged with the fields from your pre_call_webhook_param:

{
  "id": "<execution_id>",
  "agent_id": "<agent_id>",
  "status": "in-progress",
  "telephony_data": { "...": "..." },
  "...": "...",

  "transfer_reason": "caller asked for billing support",
  "conversation_summary": "Caller could not resolve a billing issue with the agent.",
  "transferred_to": "+19876543210",
  "channel": "voice"
}

Because the call is still in progress when the pre-call webhook fires, fields that are only finalized at call end (transcript, cost, summary) won’t be complete yet.

URL resolution rules

`pre_call_webhook_param`	`pre_call_webhook_url`	Result
Set	Set	Webhook sent to the transfer tool’s `pre_call_webhook_url`.
Set	Not set	Webhook sent to the agent-level Webhook URL (the same URL used for post-call execution webhooks).
Not set	Set or not set	No pre-call webhook fires.

pre_call_webhook_param is the master switch. If it is not set, no pre-call webhook fires — even if pre_call_webhook_url is configured. The agent’s normal post-call webhook is unaffected.

Agent-level URL fallback: when pre_call_webhook_param is set without a pre_call_webhook_url, the pre-call webhook is sent to your agent’s configured Webhook URL. If you already use that endpoint for post-call execution webhooks, it will now also receive pre-call webhooks. Distinguish them by the in-progress status and the extra fields from your pre_call_webhook_param.

UI configuration

In the agent dashboard, the Transfer Call configuration modal has a Send a pre-call webhook before transfer toggle. Turning it on reveals two inputs:

Pre-call webhook URL — the endpoint to notify (pre_call_webhook_url). Leave blank to use the agent-level Webhook URL.
Pre-call webhook parameters — the JSON body template with %(field)s substitution (pre_call_webhook_param).

Both save with the transfer tool and round-trip on edit.

How to set up call transfer

Open Tools Tab

Navigate to the Tools Tab in your agent configuration.

Add Transfer Call

Find Transfer Call in the tool catalog and click Add.

Configure the Destination

Enter the phone number where calls should be transferred. On Plivo telephony or a SIP trunk you can instead choose SIP trunk (URI) and enter a SIP URI with optional custom SIP headers.

Write a Clear Description

Describe when the transfer should trigger - e.g., “Transfer when caller asks for sales, pricing, or demos.”

Add Pre-tool Message

Set the message your agent speaks while initiating the transfer.

(Optional) Enable a Pre-call Webhook

Toggle Send a pre-call webhook before transfer to notify your system before the transfer happens — see Pre-call Webhook.

Save Configuration

Click Save transfer call to apply your settings.

Multiple departments? Add separate transfer functions for Sales, Support, Billing - each with its own phone number and trigger description.

Example conversation

Caller requests human agent

Caller: “I’d like to speak with someone from your sales team.”Agent: “Sure, I’ll transfer you to our sales team. Please wait a moment…”Agent triggers transfer_call function → Call is routed to configured sales number

Best practices

Be specific

Use detailed descriptions like “Transfer to sales when caller asks about pricing, demos, or purchasing” instead of generic “Transfer call”

Test phone numbers

Verify destination numbers are correct and always reachable before deploying

Use pre-tool messages

Always set a friendly message so callers know they’re being transferred

Handle failures

Have a fallback plan if the destination is busy or unavailable

Test before deploying! Failed transfers frustrate callers. Always verify phone numbers are correct and reachable.

Next steps

Custom functions

Build custom API integrations for your agent

Check calendar slots

Query availability via Cal.com integration

Book appointments

Schedule meetings during live calls

Tools tab guide

Complete function configuration guide

Build

Deploy

Monitor

Go live

Transfer Live calls to human agents with Bolna voice AI

What is call transfer?

Configuration options

Transfer to a SIP trunk

Custom SIP headers

UI configuration

Transfer calls on a SIP trunk

Pre-call webhook

Available substitution fields

What your endpoint receives

URL resolution rules

UI configuration

How to set up call transfer

Example conversation

Best practices

Be specific

Test phone numbers

Use pre-tool messages

Handle failures

Next steps

Custom functions

Check calendar slots

Book appointments

Tools tab guide

​What is call transfer?

​Configuration options

​Transfer to a SIP trunk

​Custom SIP headers

​UI configuration

​Transfer calls on a SIP trunk

​Pre-call webhook

​Available substitution fields

​What your endpoint receives

​URL resolution rules

​UI configuration

​How to set up call transfer

​Example conversation

​Best practices

Be specific

Test phone numbers

Use pre-tool messages

Handle failures

​Next steps

Custom functions

Check calendar slots

Book appointments

Tools tab guide

What is call transfer?

Configuration options

Transfer to a SIP trunk

Custom SIP headers

UI configuration

Transfer calls on a SIP trunk

Pre-call webhook

Available substitution fields

What your endpoint receives

URL resolution rules

UI configuration

How to set up call transfer

Example conversation

Best practices

Next steps