> ## Documentation Index
> Fetch the complete documentation index at: https://plivo.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Transfer to Human Agent

> Route AI-handled calls to a human agent via DID forwarding or authenticated SIP transfer

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

<Steps>
  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Conversation continues with human">
    The AI is replaced by the human agent. The original caller experiences a seamless handoff.
  </Step>
</Steps>

***

## 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     |

***

## Option 1: DID Forward

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

```xml theme={null}
<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.

***

## 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 AI call directly via SIP using the `<User>` element with authentication credentials.

```xml theme={null}
<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 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

<Note>
  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](/voice/concepts/sip-authentication/) for the full list.
</Note>

### Why SIP Auth Forward Is Recommended

* **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

<Steps>
  <Step title="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.
  </Step>

  <Step title="Get authentication credentials">
    Most SIP-based contact center software requires digest authentication. Get the username and password from your contact center setup.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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`).
  </Step>
</Steps>

***

## Server-Initiated Handoff

Instead of returning Dial XML, you can trigger the transfer programmatically via the [Make Call API](/voice/api/calls/) 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.

<Warning>
  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.
</Warning>

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](/voice/concepts/firewall-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:

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

***

## Troubleshooting

| Issue                                 | Solution                                                                                                              |
| ------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| Transfer fails with `sip_auth_failed` | Verify the SIP credentials match exactly. Check your contact center's auth realm.                                     |
| Transfer blocked by firewall          | Whitelist [Plivo's outbound media server IPs](/voice/concepts/firewall-network-configuration/) in your contact center |
| Agent answers but no audio            | Check codec compatibility. Most contact centers support PCMU/PCMA. Plivo defaults to these.                           |
| Caller hears silence during ring      | Use `dialMusic` attribute on `<Dial>` to play hold music while the agent is being reached                             |

***

## Full API Reference

* [Dial XML](/voice/xml/routing#dial/) — Complete reference for `<Dial>`, `<Number>`, and `<User>` elements
* [SIP Authentication](/voice/concepts/sip-authentication/) — How outbound SIP auth works
* [Voice Call API](/voice/api/calls/) — `sip_auth_username` and `sip_auth_password` for API-initiated transfers
* [Firewall and Network Configuration](/voice/concepts/firewall-network-configuration/) — Plivo IPs to whitelist

## Related

* [Connect External Phone Numbers](/voice/use-cases/connect-external-numbers/) — Route external numbers into Plivo applications
* [Build with Audio Streaming](/voice-agents/audio-streaming/overview/) — AI voice agent setup