Skip to main content
The <MultiPartyCall> element creates or joins a multi-party call (MPC) with advanced features like participant roles, coach mode for supervisors, and individual hold/mute controls.
For simple conference bridges without roles, see Conference.

​
Basic Usage

<Response>
    <MultiPartyCall role="customer" maxDuration="10000">
        my-mpc-name
    </MultiPartyCall>
</Response>

from plivo import plivoxml

response = plivoxml.ResponseElement()
response.add(plivoxml.MultiPartyCallElement(
    content='my-mpc-name',
    role='customer',
    max_duration=10000
))
print(response.to_string())

​
Participant Roles

RoleDescription
CustomerThe customer being served
AgentCustomer service representative
SupervisorCan monitor/coach agents (coach mode)
ai-agentAI agent connected via WebSocket streaming (see AI Agent Stream Attributes)

​
MPC-Level Attributes

These settings apply to the entire multi-party call:
AttributeTypeDefaultDescription
maxDurationinteger14400Max MPC duration in seconds (300-28800)
maxParticipantsinteger10Maximum participants (2-10)
recordbooleanfalseRecord the MPC
recordFileFormatstringmp3Recording format (mp3, wav)
recordMinMemberCountinteger1Min members to start recording (1 or 2)
waitForAgentbooleanfalseWhen true, the MPC waits for an agent to join before starting. Customer participants hear wait music until an agent arrives
recordCoachVoiceboolean-When true, includes the supervisor/coach voice in the call recording. When false, only agent and customer voices are recorded
startRecordingAudioURL-URL to fetch XML instructions for audio to play when recording starts
startRecordingAudioMethodstringGETHTTP method for startRecordingAudio URL. Values: GET, POST
stopRecordingAudioURL-URL to fetch XML instructions for audio to play when recording stops
stopRecordingAudioMethodstringGETHTTP method for stopRecordingAudio URL. Values: GET, POST

​
Hold Music

AttributeTypeDescription
waitMusicUrlURLMusic for participants waiting for MPC to start
waitMusicMethodstringHTTP method for waitMusicUrl
agentHoldMusicUrlURLMusic for agents on hold
agentHoldMusicMethodstringHTTP method for agent hold music
customerHoldMusicUrlURLMusic for customers on hold
customerHoldMusicMethodstringHTTP method for customer hold music

​
Callbacks

AttributeTypeDescription
statusCallbackUrlURLURL for MPC events
statusCallbackMethodstringHTTP method (GET, POST)
statusCallbackEventsstringEvents to receive (see below)
recordingCallbackUrlURLURL for recording events
recordingCallbackMethodstringHTTP method for recording callback

​
Participant-Level Attributes

These settings apply to individual participants:
AttributeTypeDefaultDescription
rolestringrequiredAgent, Supervisor, or Customer
mutebooleanfalseJoin muted
holdbooleanfalseJoin on hold
coachModebooleantrueSupervisor coach mode (supervisors only)
stayAlonebooleanfalseStay if only participant
startMpcOnEnterbooleantrueStart MPC when joining
endMpcOnExitbooleanfalseEnd MPC when leaving

​
Entry/Exit Sounds

AttributeTypeDefaultDescription
enterSoundstringbeep:1Sound on entry: none, beep:1, beep:2, or URL
enterSoundMethodstringGETHTTP method for enterSound URL
exitSoundstringbeep:2Sound on exit: none, beep:1, beep:2, or URL
exitSoundMethodstringGETHTTP method for exitSound URL

​
Actions

AttributeTypeDescription
onExitActionUrlURLURL called when participant exits
onExitActionMethodstringHTTP method (GET, POST)
relayDTMFInputsbooleanTransmit DTMF to other participants

​
AI Agent Stream Attributes

When role is set to ai-agent, use these attributes to connect an AI agent via WebSocket streaming.
AttributeTypeDefaultDescription
aiAgentStreamServiceUrlURL-WebSocket URL for the AI agent audio stream service
aiAgentStreamContentTypestringaudio/x-l16;rate=8000Audio content type for the AI agent stream
aiAgentStreamStatusCallbackUrlURL-URL for receiving AI agent stream status event callbacks
aiAgentStreamStatusCallbackMethodstringPOSTHTTP method for the AI agent status callback. Values: GET, POST
aiAgentStreamSamplingRatestring-Audio sampling rate for the AI agent stream
aiAgentStreamExtraHeadersobject{}Custom headers sent with the AI agent WebSocket connection

​
Examples

​
Supervisor Coach Mode

Supervisors with coachMode="true" can hear everyone but only agents hear them (customers cannot): Supervisor joining: 
<Response>
    <MultiPartyCall role="Supervisor" coachMode="true">
        support-call-123
    </MultiPartyCall>
</Response>
Agent joining: 
<Response>
    <MultiPartyCall role="Agent" startMpcOnEnter="true">
        support-call-123
    </MultiPartyCall>
</Response>
Customer joining: 
<Response>
    <MultiPartyCall role="Customer">
        support-call-123
    </MultiPartyCall>
</Response>

​
MPC Recording

<Response>
    <MultiPartyCall
        role="Agent"
        record="true"
        recordFileFormat="mp3"
        recordingCallbackUrl="https://example.com/recording-ready/">
        recorded-call
    </MultiPartyCall>
</Response>

​
Recording Events

  • MPCRecordingInitiated
  • MPCRecordingPaused
  • MPCRecordingResumed
  • MPCRecordingCompleted
  • MPCRecordingFailed

​
On Exit Action

Continue call flow after leaving MPC: 
<Response>
    <MultiPartyCall
        role="Customer"
        onExitActionUrl="https://example.com/post-call-survey/"
        onExitActionMethod="POST">
        support-call
    </MultiPartyCall>
</Response>

​
Custom Hold Music

<Response>
    <MultiPartyCall
        role="Agent"
        agentHoldMusicUrl="https://example.com/agent-hold.xml"
        customerHoldMusicUrl="https://example.com/customer-hold.xml"
        waitMusicUrl="https://example.com/wait-music.xml">
        call-center-mpc
    </MultiPartyCall>
</Response>
Hold music URLs must return XML with Play, Speak, or Wait elements.

​
Status Callback Events

Configure which events to receive with statusCallbackEvents:
ValueEvents Included
mpc-state-changesMPCInitialized, MPCStart, MPCEnd
participant-state-changesParticipantJoin, ParticipantExit, ParticipantMute, ParticipantUnmute, ParticipantHold, ParticipantUnhold, ParticipantCoachModeStart, ParticipantCoachModeStop
participant-speak-eventsParticipantSpeakStart, ParticipantSpeakStop
participant-digit-input-eventsParticipantDigitInput
add-participant-api-eventsAddParticipantByAPIActionInitiated, AddParticipantByAPIActionCompleted
participant-audio-eventsParticipantAudioStart, ParticipantAudioStop — triggered when audio from a participant starts or stops
<MultiPartyCall
    statusCallbackUrl="https://example.com/mpc-events/"
    statusCallbackEvents="mpc-state-changes,participant-state-changes,participant-speak-events">
    my-mpc
</MultiPartyCall>

​
Status Callback Parameters

ParameterDescription
EventNameEvent that triggered callback
EventTimestampWhen the event occurred
MPCUUIDUnique MPC identifier
MPCNameFriendly MPC name
MemberIDParticipant identifier
ParticipantRoleAgent, Supervisor, or Customer
ParticipantCallUUIDParticipant’s call UUID
ParticipantCoachModeWhether in coach mode
MPCDurationTotal MPC duration (on end)
MPCBilledDurationBilled duration
MPCBilledAmountCost in USD

​
On Exit Parameters

ParameterDescription
MPCUUIDMPC identifier
MPCFriendlyNameMPC name
MemberIDParticipant ID
ParticipantCallUUIDCall UUID
ParticipantJoinTimeWhen participant joined
ParticipantEndTimeWhen participant left
ParticipantRoleParticipant’s role

​
Conference vs Multi-party Call

FeatureConferenceMulti-party Call
Max participants2010
Participant rolesNoYes (Agent, Customer, Supervisor, AI Agent)
Coach modeNoYes
Individual hold/muteNoYes
API controlLimitedFull
Use caseSimple meetingsCall centers, support