Transfer to Human Agent

What: Hand a live call from your AI agent to a human — over a phone number, or over SIP to your contact center.
Watch out: A SIP transfer needs two Plivo IP ranges whitelisted, not one.

When your AI agent hits an escalation, a query it can’t handle, or a fallback, return <Dial> XML and Plivo bridges the caller to a human agent. You have two ways to do it. You’ll do most of this in your own application. The firewall and SIP settings at the far end aren’t yours to change — they belong to whoever runs your contact center. Those are collected in What Your Contact Center Must Do, which you can send them directly.

Two Options

Option	What It Does	Best For
DID forward	Transfer to a regular phone number	Simple call centers, agents on PSTN phones, no SIP infrastructure
SIP auth forward (recommended)	Transfer to a SIP endpoint (softphone, contact center, PBX) with credentials	Modern contact centers, softphone-based agents, lower latency

How It Works

AI agent decides to transfer

Your AI agent (Pipecat, LiveKit, etc.) detects an escalation trigger (caller asks for a human, intent unclear, etc.) and signals a transfer.

Your server returns transfer XML

Your application returns a <Dial> XML response that routes the call to either a phone number or a SIP endpoint.

Plivo places the outbound leg

Plivo dials the destination. For SIP transfers, the INVITE is sent from Plivo’s External SIP endpoint addresses, and Plivo handles authentication with the agent’s SIP infrastructure if credentials are provided.

Conversation continues with human

Plivo bridges the caller to the human agent and drops your AI agent’s leg. The caller stays on the same call throughout — there is no redial and no second ring.

If Your Call Is on a Live Audio Stream

This applies when your AI agent runs over audio streaming and the call is on a <Stream> with keepCallAlive="true". With keepCallAlive="true", the <Stream> element runs exclusively and subsequent XML executes only after the stream disconnects. Your transfer XML is subsequent XML, so it does not run while the stream is still open.

Close your bot’s WebSocket when you decide to transfer. Keep keepCallAlive="true" — closing the socket is what lets the call continue to your transfer XML, not removing the attribute.

If you stop the stream through the API rather than closing the socket, trigger the transfer first, then send DELETE /v1/Account/{auth_id}/Call/{call_uuid}/Stream/. Stopping the stream first lets the leg continue to the end of the XML document it is already running, which can end the call instead of transferring it. streamTimeout defaults to 86400 seconds. Set it to a realistic ceiling for your call shape so a stream that never closes cannot hold a call open.

Option 1: DID Forward

The simplest transfer. Dial a regular phone number using the <Number> element in your Dial XML.

<Response>
    <Speak>Connecting you to a human agent now.</Speak>
    <Dial>
        <Number>+14155551234</Number>
    </Dial>
</Response>

How It Works

Plivo originates an outbound call from your AI agent’s leg to the human agent’s phone number
When the human agent answers, the two legs are bridged
The caller and the human agent are connected, and your AI agent leaves the call

Trade-offs of a DID forward

Pros

Works with any phone - mobile, landline, or a softphone with a DID
Simple to set up - needs nothing from your network team

Cons

Outbound call cost - billed for the full duration of the transferred call
Agents need a real phone number
Less flexibility - no custom SIP headers, no routing to specific agent IDs or queues

A DID forward is also the fastest way to prove a transfer problem is not your application. If a transfer to a phone number connects but a SIP transfer to the same team doesn’t, the fault is on the SIP path — the firewall or the credentials — not in your XML.

Option 2: SIP Auth Forward (Recommended)

Most modern contact center software (Five9, Genesys, NICE, Talkdesk, custom WebRTC apps, etc.) accepts inbound SIP calls. Transfer the call directly over SIP using the <User> element.

<Response>
    <Speak>Connecting you to a human agent now.</Speak>
    <Dial>
        <User sipAuthUsername="<sip_username>" sipAuthPassword="<sip_password>">
            sip:agent@your-contact-center.example.com
        </User>
    </Dial>
</Response>

Give <User> a SIP URI with a hostname, as shown. Every example in the Dial XML reference uses this form.

How It Works

Plivo sends an initial SIP INVITE to your contact center’s SIP endpoint without credentials
If the contact center responds with 401 Unauthorized or 407 Proxy Authentication Required, the outbound SBC re-sends the INVITE with the supplied sipAuthUsername / sipAuthPassword
Contact center validates credentials; call connects
Caller and agent are bridged

sipAuthPassword is 8-128 characters, and is required whenever sipAuthUsername is set.

When passing agent IDs, queue IDs, or call context via sipHeaders, be aware that headers with reserved prefixes (PH-, Plivo, FS-, SipAuth, ZT-, Twilio) and the name ClientRegion are silently dropped. See SIP Authentication for the full list.

Trade-offs of a SIP auth forward

Pros

Lower cost - single SIP termination charge, no PSTN minutes
Lower latency - direct SIP, no PSTN intermediary
More flexibility - pass custom SIP headers, route to specific agent IDs or queues
Better for AI workflows - agents are typically already on softphones or contact center software

Cons

Needs your contact center’s cooperation - digest credentials, or its firewall opened to Plivo. Work you cannot do yourself, often behind a change-control queue you do not control
Subtler failure modes - most of the Troubleshooting table below is specific to this path

Setup

Get your contact center's SIP endpoint

Find the SIP URI provided by your contact center software (e.g., sip:queue-1@your-cc.example.com). Most platforms expose this in their admin dashboard.

Get authentication credentials

Most SIP-based contact center software requires digest authentication. Get the username and password from your contact center setup.

Open the firewall at your contact center

If your contact center filters inbound SIP by IP address, it has to whitelist Plivo first. Send them What Your Contact Center Must Do — this is the one part you cannot do yourself.

Update your AI agent's transfer logic

When your agent decides to transfer, return a <Dial> XML response with the <User> element. Set sipAuthUsername and sipAuthPassword to the credentials from Step 2. Point the SIP URI to your contact center endpoint.

Test

Trigger a transfer from your AI agent and confirm three things: the human agent’s phone rings, both sides can hear each other, and your Dial action URL receives DialStatus=completed. If authentication fails, the call ends with hangup cause sip_auth_failed (code 4240).

Server-Initiated Handoff

Instead of waiting for your answer URL to return Dial XML, you can trigger the transfer programmatically with the Transfer a Call API, which points a live call leg at a new URL. That URL returns the same <Dial> XML shown above, including sipAuthUsername and sipAuthPassword on <User>. This is useful for warm transfers where the agent application needs to consult before connecting the caller.

Test Your Transfer

Transfer to a phone number first

Point a test transfer at a phone number that reaches the same team. If this connects, your XML, your application, and your Plivo account are all working — which narrows any later failure to the SIP path.

Transfer to the SIP endpoint

Run the same transfer against your SIP endpoint. A failure here, after the phone number transfer succeeded, points at the firewall or the SIP credentials rather than at your agent logic.

Check audio in both directions

Speak from each end. Audio in one direction only means the RTP media ranges are whitelisted in one direction only.

Confirm your application reads DialStatus

Your Dial action URL should receive DialStatus and DialHangupCause, so your application can fall back or inform the caller when a handoff fails.

What Your Contact Center Must Do

Everything above happens in your own application. This section does not — it is work for whoever runs your contact center or PBX, which is often a different company. Send them this section.

Whitelist Plivo’s IP addresses

If your contact center restricts inbound SIP traffic by IP, it has to whitelist Plivo before a transfer can reach your agents.

If Plivo’s IPs are not whitelisted, the transfer fails at the network level before your contact center even sees the call. Nothing appears in its logs, because the call never arrived.

A SIP call runs over two separate connections, and they come from different Plivo IP ranges. Whitelist both — whitelisting one without the other leaves the call broken.

Connection	What it carries	Whitelist	Ports
Call setup (SIP signaling)	The INVITE that makes the agent’s phone ring	External SIP endpoints	5060 (UDP, TCP), 5061 (TCP/TLS)
Audio (RTP media)	The voice itself, in both directions	RTP media servers	10000-30000 (UDP)

The External SIP endpoint addresses are not inside any RTP media range. Whitelisting only the media server IPs leaves call setup blocked: the INVITE is dropped at the firewall, the contact center never sees the call, and the transfer fails with no trace on either side. Three more things to get right:

Whitelist the IPs in the region closest to your contact center deployment. If your contact center has agents distributed globally, whitelist all relevant regions.
If your Plivo account is in the India region, open the India tab under External SIP endpoints for call setup, and whitelist the Mumbai, India row under RTP media servers for audio.
The complete address lists by region (San Jose, Ashburn, Frankfurt, Sao Paulo, Sydney, Singapore, Mumbai) are in Firewall and Network Configuration.

Other settings that must be right

Their system must	If it doesn’t
Advertise a public IP address in its `Contact` header and SDP, not a private one	The call answers but carries no audio
Offer PCMU or PCMA	The call is rejected before the agent’s phone rings
Whitelist Plivo’s addresses without pinning the rule to a source port	Calls connect, but the line can stay open after one side hangs up
Either whitelist Plivo’s addresses, or issue SIP digest credentials for `sipAuthUsername` and `sipAuthPassword`	The call is rejected outright, with no indication that credentials were wanted

If they can’t whitelist by IP

Not every platform can whitelist by IP. Two alternatives, in order of preference:

Alternative	Use it when
SIP digest credentials	The contact center cannot whitelist by IP. Authenticate with `sipAuthUsername` and `sipAuthPassword` on `<User>` instead of relying on the source address.
Number mapping	It can neither whitelist Plivo’s addresses nor use digest authentication. Have it map one of its own phone numbers to the agent destination, then transfer to that number with `<Number>`.

Hangup Causes and Dial Status

When a transfer fails, the Dial action URL and hangup callback include specific values:

HangupCauseName	Code	DialStatus	Meaning
`sip_auth_failed`	`4240`	`failed`	SIP credentials were rejected by the remote endpoint
`sip_auth_timeout`	`4250`	`timeout`	Remote endpoint did not respond to the digest challenge
`no-answer`	—	`no-answer`	Agent did not pick up within the dial timeout
`busy`	—	`busy`	Agent endpoint is busy

Your agent application receives DialStatus and DialHangupCause on the Dial action URL, so it can detect a failed handoff and respond (e.g., retry with a different endpoint, fall back to a phone number, or inform the caller). Every hangup code is listed in Hangup Causes.

Troubleshooting

Issue	Solution
Transfer never arrives, and nothing appears in your contact center’s logs	Only the RTP media ranges are whitelisted, so the INVITE is dropped before it arrives. Whitelist the External SIP endpoints on port 5060, and confirm your endpoint is listening on that port
The Dial action URL reports an empty `DialBLegUUID`	Nobody answered, so no B-leg was created. Check the SIP URI in `<User>` against the Dial XML reference, then check that your endpoint is reachable
Transfer fails with `sip_auth_failed` (`4240`)	Verify the SIP credentials match exactly. Check your contact center’s auth realm. Some platforms authenticate by IP address instead of digest — if yours does, whitelist Plivo’s addresses rather than sending credentials
Transfer fails with `sip_auth_timeout` (`4250`)	Your endpoint is unreachable, or its SIP service isn’t running. Check both before re-testing credentials
Agent answers, but there’s no audio	Configure your SIP endpoint to advertise its public IP address. A private address in its `Contact` header or SDP leaves Plivo’s audio with nowhere to send to
Call is rejected before the agent’s phone rings	No shared audio codec. Offer PCMU or PCMA on your SIP endpoint
Audio works in one direction only	The RTP media ranges are whitelisted in one direction only. Add a rule for each direction
Call connects, but the line stays open after one side hangs up	Plivo’s in-dialog `BYE` may be sent from a different source port than the one that opened the dialog. A firewall rule pinned to source port 5060 drops it. Whitelist Plivo’s addresses without pinning a source port
Caller hears silence during ring	Use the `dialMusic` attribute on `<Dial>` to play hold music while the agent is being reached

Full API Reference

Dial XML — Complete reference for <Dial>, <Number>, and <User> elements
SIP Authentication — How outbound SIP auth works
Voice Call API — Transfer a Call, to redirect a live call leg from your server
Firewall and Network Configuration — Plivo IPs to whitelist
Hangup Causes — Every hangup code and its meaning

Connect External Phone Numbers — Route external numbers into Plivo applications
Build with Audio Streaming — AI voice agent setup
SIP REFER — Transfers started by a platform connected over Plivo SIP Trunking, which work differently from the ones on this page

Concepts

Integration Guides

Workflows

Deploy

Reference

Transfer to Human Agent

Two Options

How It Works

If Your Call Is on a Live Audio Stream

Option 1: DID Forward

How It Works

Trade-offs of a DID forward

Option 2: SIP Auth Forward (Recommended)

How It Works

Trade-offs of a SIP auth forward

Setup

Server-Initiated Handoff

Test Your Transfer

What Your Contact Center Must Do

Whitelist Plivo’s IP addresses

Other settings that must be right

If they can’t whitelist by IP

Hangup Causes and Dial Status

Troubleshooting

Full API Reference

​Two Options

​How It Works

​If Your Call Is on a Live Audio Stream

​Option 1: DID Forward

​How It Works

​Trade-offs of a DID forward

​Option 2: SIP Auth Forward (Recommended)

​How It Works

​Trade-offs of a SIP auth forward

​Setup

​Server-Initiated Handoff

​Test Your Transfer

​What Your Contact Center Must Do

​Whitelist Plivo’s IP addresses

​Other settings that must be right

​If they can’t whitelist by IP

​Hangup Causes and Dial Status

​Troubleshooting

​Full API Reference

​Related

Two Options

How It Works

If Your Call Is on a Live Audio Stream

Option 1: DID Forward

How It Works

Trade-offs of a DID forward

Option 2: SIP Auth Forward (Recommended)

How It Works

Trade-offs of a SIP auth forward

Setup

Server-Initiated Handoff

Test Your Transfer

What Your Contact Center Must Do

Whitelist Plivo’s IP addresses

Other settings that must be right

If they can’t whitelist by IP

Hangup Causes and Dial Status

Troubleshooting

Full API Reference

Related