Multiparty Calls (MPC) enable role-based conference calling with separate audio routing for agents, customers, and supervisors. Unlike standard conferences, MPCs support coach mode where supervisors can speak privately to agents without customers hearing.
The Multiparty Call Object Attribute Type Description mpc_uuidstringUnique identifier for the multiparty call. friendly_namestringUser-defined name for the MPC. Must be unique per account across all live MPCs. statusstringCurrent status. Values: Initialized, Active, Ended. creation_timetimestampWhen the MPC was created. Format: YYYY-MM-DD HH:mm:ss±hh:mm. start_timetimestampWhen the MPC started (first participant joined). end_timetimestampWhen the MPC ended. null if still active. durationintegerTotal duration in seconds. null if not ended. billed_durationintegerBillable duration in seconds. billed_amountstringTotal billed amount in USD. max_participantsintegerMaximum participants allowed. max_durationintegerMaximum duration in seconds from initiation. stay_alonebooleanWhether participants can remain alone in the MPC. recordingstringRecording status. Values: recording, not-recording, paused. participantsstringURL to the participants list. termination_causestringReason the MPC ended. termination_cause_codeintegerNumeric code for termination cause. sub_accountstringSubaccount associated with the MPC. resource_uristringURI of the MPC resource.
Example MPC Object { "billed_amount" : null , "billed_duration" : null , "creation_time" : "2020-12-24 09:20:03+00:00" , "duration" : null , "end_time" : null , "friendly_name" : "test_mpc" , "mpc_uuid" : "8742d531-292a-46aa-8754-836be1092885" , "participants" : "/v1/Account/MAOTE1OWE0MDK0MTLHYW/MultiPartyCall/name_test_mpc/Participant/" , "recording" : "not-recording" , "resource_uri" : "/v1/Account/MAOTE1OWE0MDK0MTLHYW/MultiPartyCall/name_test_mpc/" , "start_time" : "2020-12-24 09:20:03+00:00" , "status" : "Active" , "stay_alone" : false , "sub_account" : null , "termination_cause" : null , "termination_cause_code" : null }
The Participant Object Attribute Type Description member_idstringUnique ID for this participant in the MPC. mpc_uuidstringUUID of the parent multiparty call. call_uuidstringUUID of the call resource. rolestringParticipant role. Values: Agent, Customer, Supervisor. Cannot be changed after set. coach_modebooleanFor supervisors only. When true, supervisor audio is only heard by agents, not customers. join_timetimestampWhen the participant joined. Format: YYYY-MM-DD HH:mm:ss±hh:mm. exit_timetimestampWhen the participant left. null if still active. durationintegerDuration in seconds the participant was in the MPC. billed_durationintegerBillable duration in seconds. billed_amountstringAmount billed for this participant. mutebooleanWhether the participant is muted. holdbooleanWhether hold music is playing for this participant. start_mpc_on_enterbooleanWhether MPC started when this participant entered. end_mpc_on_exitbooleanWhether MPC ends when this participant leaves. participant_exit_causestringReason participant left. Values: Participant Call Hangup, Kicked Out of Multiparty Call, Multiparty Call Ended, Participant Call Transferred.
Example Participant Object { "billed_amount" : null , "billed_duration" : null , "call_uuid" : "dd473c48-34a6-4d67-a033-af590b41c23f" , "coach_mode" : false , "duration" : null , "end_mpc_on_exit" : false , "exit_cause" : null , "exit_time" : null , "hold" : false , "join_time" : "2020-12-24 10:01:56+00:00" , "member_id" : "355" , "mpc_uuid" : "4e9ae3f1-a29c-4524-a1b4-4758922e589b" , "mute" : false , "resource_uri" : "/v1/Account/MAOTE1OWE0MDK0MTLHYW/MultiPartyCall/name_test_mpc_1/Participant/355/" , "role" : "agent" , "start_mpc_on_enter" : true }
Retrieve a Multiparty Call Get details of a specific multiparty call.
GET https://api.plivo.com/v1/Account/{auth_id}/MultiPartyCall/name_{mpc_name}/ GET https://api.plivo.com/v1/Account/{auth_id}/MultiPartyCall/uuid_{mpc_uuid}/
You can fetch details using the MPC name only for ongoing calls. For ended calls, use the UUID.
Python
Ruby
Node
PHP
Java
.NET
Go
cURL
import plivo client = plivo.RestClient( '<auth_id>' , '<auth_token>' ) response = client.multi_party_calls.get( friendly_name = 'mpc_name' ) # Or by UUID response = client.multi_party_calls.get( uuid = '8742d531-292a-46aa-8754-836be1092885' ) print (response)
List All Multiparty Calls Retrieve all multiparty calls with optional filters.
GET https://api.plivo.com/v1/Account/{auth_id}/MultiPartyCall/
Arguments Parameter Description friendly_nameFilter by MPC name. statusFilter by status. Values: initialized, active, ended. termination_cause_codeFilter by termination code: 1000 (No Active Participants), 1010 (Stay Alone Not Permitted), 2000 (Max Duration Reached), 3000 (Hangup API Triggered). end_timeFilter by end time. Supports __gt, __gte, __lt, __lte. Format: YYYY-MM-DD HH:MM[:ss]. creation_timeFilter by creation time. Same format and suffixes as end_time. limitResults per page. Max: 20. Default: 20. offsetNumber of records to skip for pagination.
Python
Ruby
Node
PHP
Java
.NET
Go
cURL
import plivo client = plivo.RestClient( '<auth_id>' , '<auth_token>' ) response = client.multi_party_calls.list() print (response)
Response { "api_id" : "ed93aea0-45cd-11eb-8530-0242ac110006" , "meta" : { "count" : 2 , "limit" : 20 , "next" : null , "offset" : 0 , "previous" : null }, "objects" : [ { "billed_amount" : "0.05000" , "billed_duration" : 60 , "creation_time" : "2020-12-24 15:23:38+05:30" , "duration" : 2 , "end_time" : "2020-12-24 15:23:40+05:30" , "friendly_name" : "test_mpc_1" , "mpc_uuid" : "4ed623a5-9f3e-45e0-9e7e-3d19a94b3bd3" , "status" : "Ended" , "termination_cause" : "No Active Participants" , "termination_cause_code" : 1000 } ] }
Activate a Multiparty Call Activate an MPC that was initialized with start_mpc_on_enter set to false.
POST https://api.plivo.com/v1/Account/{auth_id}/MultiPartyCall/name_{mpc_name}/
Arguments Parameter Description statusRequired. Set to Active to start the MPC.
Python
Ruby
Node
PHP
Java
.NET
Go
cURL
import plivo client = plivo.RestClient( '<auth_id>' , '<auth_token>' ) response = client.multi_party_calls.start( friendly_name = 'mpc_name' ) print (response)
Response End a Multiparty Call Terminate an ongoing MPC.
DELETE https://api.plivo.com/v1/Account/{auth_id}/MultiPartyCall/name_{mpc_name}/
When the MPC ends:
Participants added via XML proceed to the next element or onExitActionUrl
Participants added via API are disconnected with hangup cause code 4020 or proceed to on_exit_action_url
Python
Ruby
Node
PHP
Java
.NET
Go
cURL
import plivo client = plivo.RestClient( '<auth_id>' , '<auth_token>' ) response = client.multi_party_calls.stop( friendly_name = 'mpc_name' ) print (response)
Response Add a Participant Add a participant to an existing MPC or start a new MPC. Plivo creates a new MPC if no ongoing call with the given name exists.
POST https://api.plivo.com/v1/Account/{auth_id}/MultiPartyCall/name_{mpc_name}/Participant/
Required Arguments Parameter Description roleParticipant role. Values: agent, supervisor, customer. fromCaller ID for the outbound call (E.164 format or SIP endpoint). toDestination number or SIP endpoint.
Optional Arguments Parameter Default Description caller_nameCaller name for SIP endpoints. call_uuidAdd an existing call to the MPC. call_status_callback_urlURL for call status events. call_status_callback_methodPOSTHTTP method for status callbacks. confirm_keyDTMF key participant must press to join. confirm_key_sound_urlAudio to play before confirm key. dial_musicRealMusic/ringtone while connecting. Use real for ringback or URL. ring_timeout45 Seconds to ring before timeout. max_duration14400 Max call duration in seconds. max_participants10 Max participants allowed (2-10). record_min_member_count1 Min members before recording starts. wait_music_urlMusic URL while waiting for MPC to start. agent_hold_music_urlHold music URL for agents. customer_hold_music_urlHold music URL for customers. recording_callback_urlURL for recording events. status_callback_urlURL for participant status events. on_exit_action_urlURL to fetch XML when participant exits. stay_alonefalseAllow participant to stay alone. coach_modetrueFor supervisors: whether to whisper to agents only. mutefalseJoin muted. holdfalseJoin on hold. start_mpc_on_entertrueStart MPC when participant joins. end_mpc_on_exitfalseEnd MPC when participant leaves. enter_soundbeep:1Sound when joining. Values: beep:1, beep:2, none, or URL. enter_sound_methodGETHTTP method for enter_sound URL. exit_soundbeep:2Sound when leaving. Same values as enter_sound.
Python
Ruby
Node
PHP
Java
.NET
Go
cURL
import plivo client = plivo.RestClient( '<auth_id>' , '<auth_token>' ) response = client.multi_party_calls.add_participant( friendly_name = 'mpc_name' , role = 'agent' , from_ = '+14151234567' , to_ = '+14157654321' , start_mpc_on_enter = True , enter_sound = 'beep:1' ) print (response)
Retrieve a Participant Get details of a specific participant.
GET https://api.plivo.com/v1/Account/{auth_id}/MultiPartyCall/name_{mpc_name}/Participant/{member_id}/
Python
Ruby
Node
PHP
Java
.NET
Go
cURL
import plivo client = plivo.RestClient( '<auth_id>' , '<auth_token>' ) response = client.multi_party_calls.get_participant( participant_id = '355' , friendly_name = 'mpc_name' ) print (response)
List All Participants Retrieve all participants in a multiparty call.
GET https://api.plivo.com/v1/Account/{auth_id}/MultiPartyCall/name_{mpc_name}/Participant/
Python
Ruby
Node
PHP
Java
.NET
Go
cURL
import plivo client = plivo.RestClient( '<auth_id>' , '<auth_token>' ) response = client.multi_party_calls.list_participants( friendly_name = 'mpc_name' ) print (response)
Response { "api_id" : "2de9cf75-9606-11eb-8ca5-0242ac110006" , "meta" : { "count" : 3 , "limit" : 20 , "offset" : 0 }, "objects" : [ { "call_uuid" : "58e76e86-54b8-402e-9d83-a16e29b6582c" , "coach_mode" : true , "hold" : false , "member_id" : "229" , "mpc_uuid" : "d5c8be43-87d0-4ba6-90a1-011bb6ab0a00" , "mute" : false , "role" : "supervisor" }, { "call_uuid" : "9def1955-870f-4052-84ca-02063d24105d" , "coach_mode" : false , "hold" : false , "member_id" : "228" , "mpc_uuid" : "d5c8be43-87d0-4ba6-90a1-011bb6ab0a00" , "mute" : false , "role" : "customer" }, { "call_uuid" : "b4e8210e-9cd5-4d92-b989-2ff889ee0e1f" , "coach_mode" : false , "hold" : false , "member_id" : "226" , "mpc_uuid" : "d5c8be43-87d0-4ba6-90a1-011bb6ab0a00" , "mute" : false , "role" : "agent" } ] }
Update a Participant Mute, unmute, hold, or unhold a participant. Can also toggle coach mode for supervisors.
POST https://api.plivo.com/v1/Account/{auth_id}/MultiPartyCall/name_{mpc_name}/Participant/{member_id}/
The {member_id} can be a specific ID, comma-separated list, or all to affect all participants.
Arguments Parameter Description mutetrue to mute, false to unmute.holdtrue to hold (plays hold music), false to unhold.coach_modeFor supervisors only. true = whisper to agents only, false = audible to all.
coach_mode can only be updated for individual participants, not with all.
Python
Ruby
Node
PHP
Java
.NET
Go
cURL
import plivo client = plivo.RestClient( '<auth_id>' , '<auth_token>' ) response = client.multi_party_calls.update_participant( participant_id = '355' , friendly_name = 'mpc_name' , mute = True , hold = False ) print (response)
Response { "api_id" : "03042285-45d9-11eb-9014-0242ac110003" , "mute" : "MPC: test_mpc_1 mute/unmute member(s) succeeded" , "hold" : "MPC: test_mpc_1 hold/unhold member(s) succeeded" }
Kick a Participant Remove a participant from the MPC.
DELETE https://api.plivo.com/v1/Account/{auth_id}/MultiPartyCall/name_{mpc_name}/Participant/{member_id}/
The {member_id} can be a specific ID, comma-separated list, or all to kick all participants.
Python
Ruby
Node
PHP
Java
.NET
Go
cURL
import plivo client = plivo.RestClient( '<auth_id>' , '<auth_token>' ) response = client.multi_party_calls.kick_participant( participant_id = '355' , friendly_name = 'mpc_name' ) print (response)
Response Record a Multiparty Call Start Recording
Stop Recording
Pause Recording
Resume Recording
Start recording the entire MPC. POST https://api.plivo.com/v1/Account/{auth_id}/MultiPartyCall/name_{mpc_name}/Record/
Arguments Parameter Default Description file_formatmp3Recording format. Values: mp3, wav. recording_callback_urlURL for recording status events. recording_callback_methodPOSTHTTP method for callbacks.
A supervisor’s voice is recorded regardless of coach_mode setting.
Python
Ruby
Node
PHP
Java
.NET
Go
cURL
import plivo client = plivo.RestClient( '<auth_id>' , '<auth_token>' ) response = client.multi_party_calls.start_recording( friendly_name = 'mpc_name' , file_format = 'mp3' , recording_callback_url = 'https://example.com/recording-status' ) print (response)
Response { "api_id" : "e05b5263-45dc-11eb-9014-0242ac110003" , "message" : "MPC: test_mpc_1 record started" , "recording_id" : "e06ac332-45dc-11eb-94fe-06dd7f581a50" , "recording_url" : "https://media.plivo.com/v1/Account/MAOTE1OWE0MDK0MTLHYW/Recording/e06ac332-45dc-11eb-94fe-06dd7f581a50.mp3" }
Stop MPC recording. DELETE https://api.plivo.com/v1/Account/{auth_id}/MultiPartyCall/name_{mpc_name}/Record/
Python
Ruby
Node
PHP
Java
.NET
Go
cURL
import plivo client = plivo.RestClient( '<auth_id>' , '<auth_token>' ) response = client.multi_party_calls.stop_recording( friendly_name = 'mpc_name' ) print (response)
Response Pause ongoing MPC recording. POST https://api.plivo.com/v1/Account/{auth_id}/MultiPartyCall/name_{mpc_name}/Record/Pause/
import plivo client = plivo.RestClient( '<auth_id>' , '<auth_token>' ) response = client.multi_party_calls.pause_recording( friendly_name = 'mpc_name' ) print (response)
Response Resume paused MPC recording. POST https://api.plivo.com/v1/Account/{auth_id}/MultiPartyCall/name_{mpc_name}/Record/Resume/
import plivo client = plivo.RestClient( '<auth_id>' , '<auth_token>' ) response = client.multi_party_calls.resume_recording( friendly_name = 'mpc_name' ) print (response)
Response Recording Callback Events Events sent to recording_callback_url:
MPCRecordingInitiatedMPCRecordingPausedMPCRecordingResumedMPCRecordingCompletedMPCRecordingFailed
Parameter Description EventNameThe recording event type. EventTimestampWhen the event occurred. MPCNameName of the MPC. MPCUUIDUUID of the MPC. RecordingDurationDuration in seconds. RecordingFormatFile format (mp3/wav). RecordingURLURL to download the recording. RecordingUUIDUnique recording identifier. RecordingStartTimeWhen recording started. RecordingEndTimeWhen recording ended. SequenceNumberEvent sequence number.
Record a Participant Record a specific participant’s audio.
Start Recording
Stop Recording
POST https://api.plivo.com/v1/Account/{auth_id}/MultiPartyCall/{mpc_name}/Participant/{member_id}/Record/
Arguments Parameter Default Description file_formatmp3Recording format. Values: mp3, wav. recording_callback_urlURL for recording status events. recording_callback_methodPOSTHTTP method for callbacks. record_track_typeallTrack type. Values: participant (single-track), all (multi-channel), both.
import plivo client = plivo.RestClient( '<auth_id>' , '<auth_token>' ) response = client.multi_party_calls.start_participant_recording( participant_id = '355' , friendly_name = 'mpc_name' , file_format = 'mp3' ) print (response)
DELETE https://api.plivo.com/v1/Account/{auth_id}/MultiPartyCall/{mpc_name}/Participant/{member_id}/Record/
Parameter Default Description record_track_typeallWhich recording to stop. Values: participant, all, both.
import plivo client = plivo.RestClient( '<auth_id>' , '<auth_token>' ) response = client.multi_party_calls.stop_participant_recording( participant_id = '355' , friendly_name = 'mpc_name' ) print (response)
Play Audio to Participant Start Playing
Stop Playing
Play an audio file to specific participants. POST https://api.plivo.com/v1/Account/{auth_id}/MultiPartyCall/name_{mpc_name}/Member/{member_id}/Play/
The {member_id} can be a specific ID, comma-separated list, or all. Arguments Parameter Description urlsRequired. URL of the audio file (.mp3 or .wav).
import plivo client = plivo.RestClient( '<auth_id>' , '<auth_token>' ) response = client.multi_party_calls.start_play_audio( participant_id = '355' , friendly_name = 'mpc_name' , url = 'https://example.com/audio.mp3' ) print (response)
Response { "api_id" : "e05b5263-45dc-11eb-9014-0242ac110003" , "message" : "play queued into MPC" , "mpcMemberId" : [ "355" ], "mpcName" : "test_mpc_1" }
Stop playing audio to participants. DELETE https://api.plivo.com/v1/Account/{auth_id}/MultiPartyCall/name_{mpc_name}/Member/{member_id}/Play/
Use the same member_id format you used to start playing. If you started with a specific ID, stopping with all won’t work.
import plivo client = plivo.RestClient( '<auth_id>' , '<auth_token>' ) response = client.multi_party_calls.stop_play_audio( participant_id = '355' , friendly_name = 'mpc_name' ) print (response)
Response 
