Skip to main content
A common pattern in AI voice agents is handing off a call to a human agent for escalation, complex queries, or fallback. Plivo supports two transfer methods.

​
How It Works

1

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.
2

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.
3

Plivo connects the call

Plivo bridges the caller to the human agent. For SIP transfers, Plivo handles authentication with the agent’s SIP infrastructure if credentials are provided.
4

Conversation continues with human

The AI is replaced by the human agent. The original caller experiences a seamless handoff.

​
Two Options

OptionWhat It DoesBest For
DID forwardTransfer to a regular phone numberSimple call centers, agents on PSTN phones, no SIP infrastructure
SIP auth forward (recommended)Transfer to a SIP endpoint (softphone, contact center, PBX) with credentialsModern contact centers, softphone-based agents, lower latency

​
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 agent’s phone number
  • When the agent answers, the two legs are bridged
  • Caller and agent are connected; AI agent leaves the call

​
Trade-offs

  • Pros: Works with any phone (mobile, landline, softphone with a DID). Simple to set up.
  • Cons: Outbound call cost. Agents need a real phone number. Less flexibility for agent routing logic.
Most modern contact center software (Five9, Genesys, NICE, Talkdesk, custom WebRTC apps, etc.) accepts inbound SIP calls. Transfer the AI call directly via SIP using the <User> element with authentication credentials. 
<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>

​
How It Works

  • Plivo sends a SIP INVITE to your contact center’s SIP endpoint
  • If the contact center responds with 407 Proxy Authentication Required, Plivo computes the digest response using the credentials you provided
  • Plivo re-sends the INVITE with auth headers; call connects
  • Caller and agent are bridged
  • 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

​
Setup

1

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.
2

Get authentication credentials

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

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.
4

Test

Trigger a transfer from your AI agent. The call should connect to the human agent. If authentication fails, the call ends with hangup cause sip_auth_failed (code 4240).

​
Server-Initiated Handoff

Instead of returning Dial XML, you can trigger the transfer programmatically via the Make Call API using sip_auth_username and sip_auth_password. This is useful for warm transfers where the agent application needs to consult before connecting the caller.

​
Whitelist Plivo’s IPs at Your Contact Center

If your contact center restricts inbound SIP traffic by IP, you need to whitelist Plivo’s outbound media server IPs so that transferred calls from Plivo can reach your agents.
If Plivo’s IPs are not whitelisted at your contact center, the transfer will fail at the network level before your contact center even sees the call.
For the complete list of Plivo’s media server IPs by region (San Jose, Ashburn, Frankfurt, Sao Paulo, Sydney, Singapore, Mumbai), see Voice Firewall and Network Configuration. Whitelist the IPs in the region closest to your contact center deployment. If your contact center has agents distributed globally, whitelist all relevant regions.

​
Hangup Causes and Dial Status

When a transfer fails, the Dial action URL and hangup callback include specific values:
HangupCauseNameCodeDialStatusMeaning
sip_auth_failed4240failedSIP credentials were rejected by the remote endpoint
sip_auth_timeout4250timeoutRemote endpoint did not respond to the digest challenge
no-answer—no-answerAgent did not pick up within the dial timeout
busy—busyAgent 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).

​
Troubleshooting

IssueSolution
Transfer fails with sip_auth_failedVerify the SIP credentials match exactly. Check your contact center’s auth realm.
Transfer blocked by firewallWhitelist Plivo’s outbound media server IPs in your contact center
Agent answers but no audioCheck codec compatibility. Most contact centers support PCMU/PCMA. Plivo defaults to these.
Caller hears silence during ringUse dialMusic attribute on <Dial> to play hold music while the agent is being reached

​
Full API Reference