> ## 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 a Human Agent with a Multiparty Call

> Hand an AI-handled call to a human agent inside a Multiparty Call, as a cold transfer or a warm transfer where the AI agent briefs the human agent.

> [!NOTE]
>
> * **What:** Put the caller, your AI agent, and the human agent in one Multiparty Call (MPC), for a cold or warm transfer.
> * **Watch out:** In a warm transfer, [hold the caller, don't mute them](#warm-transfer-with-a-multiparty-call).

Put the caller and your AI agent in a [Multiparty Call](/docs/voice/xml/multiparty-call/) (MPC). Your AI agent joins as a participant with the `ai-agent` role. When you transfer, the human agent joins as another participant. Use it for two cases:

* **The transfer doesn't wait for your AI agent's WebSocket to close.** The caller's call runs `<MultiPartyCall>`, not `<Stream>`, so nothing holds the transfer back.
* **Warm transfer.** Your AI agent stays in the MPC and briefs the human agent while the caller is on hold, then leaves.

## How a Multiparty Call Transfer Works

![Cold transfer in three steps. 1: the AI agent answers the caller. 2: the human agent joins the Multiparty Call. 3: the AI agent is removed and the caller talks to the human agent.](https://mintcdn.com/plivo/9zIRdvx4doyoicBb/images/transfer-to-human-agent/mpc-cold-transfer-light.svg?fit=max\&auto=format\&n=9zIRdvx4doyoicBb\&q=85\&s=5a31a7ba6828c056fd95b526b1635758)

* The caller joins the MPC, usually through their answer XML.
* Your server adds your AI agent to the MPC through the [Add a Participant](/docs/voice/api/multiparty-calls/#add-a-participant) API. Your AI agent connects over WebSocket, the same way it does with `<Stream>`: it receives `start` and `media` events and sends audio back with `playAudio` ([Stream Event Protocol](/docs/voice-agents/audio-streaming/concepts/audio-streaming-reference/)).
* Either can join first. You can add your AI agent first, then add the caller with Add a Participant and the `customer` role, so your AI agent is ready when they answer.
* To transfer, your server adds the human agent, at a phone number or a SIP endpoint.
* Your server removes your AI agent with the [Kick a Participant](/docs/voice/api/multiparty-calls/#kick-a-participant) API. The caller and the human agent stay connected.
* When the human agent hangs up, your server ends the MPC with the [End a Multiparty Call](/docs/voice/api/multiparty-calls/#end-a-multiparty-call) API.

## Trade-offs of a Multiparty Call

**Pros**

* **No wait on your WebSocket** - the human agent joins while your AI agent's WebSocket is still open
* **Warm transfer** - your AI agent can brief the human agent before the caller is connected
* **Same AI agent code** - an AI agent built for `<Stream>` connects with the same events

**Cons**

* **More work on your server** - it tracks each participant's `MemberID` and makes an API call for each step of the transfer
* **Your server must control the call** - it puts the caller in the MPC, so it doesn't fit an AI platform that serves the answer URL for you

## Set Up a Multiparty Call Transfer

These steps start with the caller. Return this answer XML for the call. Give each call its own MPC name, because [Add a Participant](/docs/voice/api/multiparty-calls/#add-a-participant) joins any ongoing MPC with the same name.

```xml theme={null}
<Response>
    <MultiPartyCall role="customer" stayAlone="true" endMpcOnExit="true"
        statusCallbackUrl="https://example.com/mpc-events"
        statusCallbackEvents="participant-state-changes">
        call-1234
    </MultiPartyCall>
</Response>
```

* `stayAlone="true"` keeps the caller in the MPC while they're its only participant, before your AI agent joins.
* `endMpcOnExit="true"` ends the MPC when the caller hangs up.
* `participant-state-changes` sends a `ParticipantJoin` event to `statusCallbackUrl` each time a participant joins. Save the `MemberID` from each one. You need the caller's to hold them and your AI agent's to remove it. The event parameters are listed in [Status Callback Parameters](/docs/voice/xml/multiparty-call/#status-callback-parameters).

**1. Add your AI agent.** When the caller's `ParticipantJoin` arrives, add your AI agent with the `ai-agent` role. `to` is required, but Plivo doesn't dial it for an `ai-agent` participant: set it to any Plivo number on your account. Set `ai_agent_stream_content_type` to the audio format your AI agent already uses on `<Stream>`. The default is `audio/x-l16;rate=8000`.

```bash theme={null}
curl -X POST "https://api.plivo.com/v1/Account/{auth_id}/MultiPartyCall/name_call-1234/Participant/" \
  -u '<auth_id>:<auth_token>' \
  -H "Content-Type: application/json" \
  -d '{
    "role": "ai-agent",
    "from": "+14151234567",
    "to": "<any_plivo_number_on_your_account>",
    "ai_agent_stream_service_url": "wss://your-ai-agent.example.com/stream",
    "ai_agent_stream_content_type": "audio/x-l16;rate=8000"
  }'
```

**2. Add the human agent.** When your AI agent decides to transfer, add the human agent with the `agent` role. Set `to` to a phone number or a SIP endpoint.

```bash theme={null}
curl -X POST "https://api.plivo.com/v1/Account/{auth_id}/MultiPartyCall/name_call-1234/Participant/" \
  -u '<auth_id>:<auth_token>' \
  -H "Content-Type: application/json" \
  -d '{
    "role": "agent",
    "from": "+14151234567",
    "to": "+14155551234"
  }'
```

**3. Remove your AI agent.** When the human agent's `ParticipantJoin` arrives, kick your AI agent. This is a cold transfer.

```bash theme={null}
curl -X DELETE "https://api.plivo.com/v1/Account/{auth_id}/MultiPartyCall/name_call-1234/Participant/<ai_agent_member_id>/" \
  -u '<auth_id>:<auth_token>'
```

**4. End the MPC when the human agent hangs up.** When the human agent's `ParticipantExit` arrives, end the MPC with [End a Multiparty Call](/docs/voice/api/multiparty-calls/#end-a-multiparty-call). Without this, the caller stays alone in the MPC after the human agent hangs up, because `stayAlone` is `true`.

If the human agent doesn't answer, no `ParticipantJoin` arrives for them. Your AI agent is still in the call, so it can tell the caller or try another human agent. To get the result of each dial, add `add-participant-api-events` to `statusCallbackEvents`.

## Warm Transfer with a Multiparty Call

![Warm transfer in three steps. 1: the AI agent answers the caller. 2: the caller waits on hold while the AI agent briefs the human agent. 3: the caller is taken off hold, the AI agent is removed, and the caller talks to the human agent.](https://mintcdn.com/plivo/9zIRdvx4doyoicBb/images/transfer-to-human-agent/mpc-warm-transfer-light.svg?fit=max\&auto=format\&n=9zIRdvx4doyoicBb\&q=85\&s=aebade69736d8c5d73bfb49bf19903ba)

In a warm transfer, your AI agent briefs the human agent before the caller is connected. Use the setup above and hold the caller around step 2:

1. Hold the caller: update the caller's participant with `hold` set to `true`.
2. Add the human agent (step 2 above).
3. Your AI agent briefs the human agent. They hear each other, and the caller hears neither.
4. Unhold the caller: update the caller's participant with `hold` set to `false`.
5. Remove your AI agent (step 3 above). The caller and the human agent are now connected.

```bash theme={null}
curl -X POST "https://api.plivo.com/v1/Account/{auth_id}/MultiPartyCall/name_call-1234/Participant/<caller_member_id>/" \
  -u '<auth_id>:<auth_token>' \
  -H "Content-Type: application/json" \
  -d '{"hold": true}'
```

> [!WARNING]
>
> Hold the caller. Don't mute them. A muted participant can't be heard but still hears everyone in the MPC, so a muted caller hears your AI agent brief the human agent. A held caller hears none of the briefing, and nobody hears them.

To play your own hold music, set `customerHoldMusicUrl` on `<MultiPartyCall>`. The URL must return XML with `Play`, `Speak`, or `Wait` elements ([Custom Hold Music](/docs/voice/xml/multiparty-call/#custom-hold-music)). A URL that returns an audio file directly leaves the held caller in silence.

***

## Related

* [Transfer to Human Agent](/docs/voice/use-cases/transfer-to-human-agent/) — When to transfer, and how to choose an option
* [Option 1: DID Forward](/docs/voice/use-cases/transfer-to-human-agent/did-forward/) — Transfer to a phone number
* [Option 2: SIP Auth Forward](/docs/voice/use-cases/transfer-to-human-agent/sip-auth-forward/) — Transfer to a SIP endpoint with credentials
* [Troubleshoot Transfer to Human Agent](/docs/voice/use-cases/transfer-to-human-agent/troubleshooting/) — Test a transfer and fix failed ones
* [Multiparty Call XML](/docs/voice/xml/multiparty-call/) — `<MultiPartyCall>` and its participant roles
* [Multiparty Call API](/docs/voice/api/multiparty-calls/) — Add, update, kick participants, and end the MPC