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