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.

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

Put the caller and your AI agent in a 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

• The caller joins the MPC, usually through their answer XML.
• Your server adds your AI agent to the MPC through the 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).
• 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 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 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 joins any ongoing MPC with the same name.

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

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.

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": "[phone]",
    "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.

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": "[phone]",
    "to": "[phone]"
  }'

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

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

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.

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}'

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). A URL that returns an audio file directly leaves the held caller in silence.

---

​

Related

• Transfer to Human Agent — When to transfer, and how to choose an option
• Option 1: DID Forward — Transfer to a phone number
• Option 2: SIP Auth Forward — Transfer to a SIP endpoint with credentials
• Troubleshoot Transfer to Human Agent — Test a transfer and fix failed ones
• Multiparty Call XML — <MultiPartyCall> and its participant roles
• Multiparty Call API — Add, update, kick participants, and end the MPC