import plivo

client = plivo.RestClient(auth_id="<auth_id>", auth_token="<auth_token>")

call_params = {
    'role': "Agent",
    'start_mpc_on_enter': True,
    'from_': "<caller_id>", # Caller ID for the outbound call
    'to_': "<destination_number>", # The destination phone number or endpoint username of the participant to be added
    "enter_sound": "none"
}
response = client.multi_party_calls.add_participant(friendly_name="testmpc", **call_params)
print(response)
Use the Participant API to add a participant to an ongoing multiparty call (MPC) or to start a new multiparty call and add the participant to it.

API Endpoint

POST
https://api.plivo.com/v1/Account/{auth_id}/MultiPartyCall/name_{mpc_name}/Participant/

Add a participant to a multiparty call using API

You can add a participant to a multiparty call in two ways:
  1. Using the <MultiPartyCall> element in the Answer URL
  2. Using MultiPartyCall REST API
Plivo initiates a new multiparty call if no ongoing MPC is found in the account (or subaccount) with the given friendly name.

Arguments

ArgumentDescription
from
Required — Conditional
The “from” number to use as the caller ID for this outbound call.
to
Required — Conditional
A single destination or a list of destinations (numbers or endpoints) to call. The first destination to answer (and accept) the call should be added to the MPC. Other destinations should be automatically hung up with the hangup cause LOST RACE.

Note that parallel dialing is supported only when dialing out to Agent role users. The API will return an error if multiple destination numbers are specified and the role is not Agent.

Note that these outbound calls are queued and dequeued as per the calls per second (CPS) configured for your account. You can find more details in the account limits guide.

Multiple “to” numbers must be delimited by ”<” — for example, 14156667777<14156667778<sip:john1234@phone.plivo.com.
call_uuid
Required — Conditional
The UUID of the call that should be transferred to the MPC specified in the API request.

If an MPC with a given name does not exist, then Plivo will create a new MPC and add the participant.
role
Required
Allowed values: Agent, Supervisor, Customer
caller_name
string
If set to a string, caller name will be set to this string value.

Allowed values: Any string.
Defaults to Caller’s caller_name.
Character limit — 50 characters.
call_status_callback_url
string
Plivo invokes this URL when the call state changes. Only events for newly initiated calls are transmitted.

Events are not generated for existing calls being transferred into this MPC.
call_status_callback_method
string
The HTTP verb that should be used to invoke the URL configured as call_status_callback_url.

Allowed values: GET, POST
Defaults to POST.
confirm_key
string
If a value is provided, the call recipient must enter the key specified to be bridged into the MPC.

If the call recipient fails to provide the correct input within 30 seconds, then the call will be disconnected with hangup cause code 9110.

Allowed values: One of 0,1,2,3,4,5,6,7,8,9,#,*
confirm_key_sound_url
string
Remote URL fetched with GET HTTP request that must return an XML document with Play, Wait, and/or Speak elements only (all others are ignored).

The sound indicated by the XML document is played to the called party when the call is answered.

If not provided, then Plivo will play this message on the call: “Please enter confirm_key to accept the call.”
confirm_key_sound_method
string
HTTP verb that should be used to invoke the URL configured as confirm_key_sound_url.

Allowed values: GET, POST
Defaults to GET.
ring_timeout
integer
The number of seconds to wait for the call to be answered, counted from the call initiation time.

Allowed values: 15 to 120
Defaults to 45.
delay_dial
integer
The number of seconds to wait before dialing out the ‘to’ destination(s).
Counted from the call initiation time.
For multiple dial destinations in the ‘to’ parameter, a single or multiple delay values can be passed separated by ’<’.
If a single value is passed then it applies to all destinations
If multiple values are passed, then they will be applied to the destinations in the same order as they appear.
In line with expected parallel dial behavior, if one of the dialed destinations is answered before this delay is over then the corresponding destination(s) should not be dialed at all.

Allowed values: Integer between 0 to 120

Defaults to 0.
max_duration
integer
Sets the maximum duration (in seconds) of the MPC resource. The MPC will end after this period.

Maximum duration is counted from the call initiation time.

Allowed values: 300 (five minutes) to 28,800 (eight hours)
Defaults to 14,400 (four hours).
max_participants
integer
The maximum number of participants. Sets the Max Participants property of the MPC resource.

Allowed values: 2 to 10
Defaults to 10.
wait_music_url
string
Remote URL fetched with HTTP GET request. The URL must return an XML document with Play, Speak, and/or Wait elements only. All other elements are ignored.

This audio is played in a loop to participants waiting for the MPC to begin.

Defaults to Plivo’s default wait music.

If the URL is not reachable or does not return a valid XML document, no music will be played.
wait_music_method
string
The HTTP verb that should be used to invoke the URL configured as wait_music_url.

Allowed values: GET, POST
Defaults to GET.
agent_hold_music_url
string
Remote URL fetched with HTTP GET request. The URL must return an XML document with Play, Speak, and/or Wait elements only. All other elements are ignored.

This audio is played to Agents while they’re on hold. Sets the Agent Hold Music URL property of the MPC resource.

Defaults to Plivo’s default hold music.

If the URL is not reachable or does not return a valid XML document, no music will be played.
agent_hold_music_method
string
The HTTP verb that should be used to invoke the URL configured as agent_hold_music_url.

Allowed values: GET, POST
Defaults to GET.
customer_hold_music_url
string
Remote URL fetched with HTTP GET request. The URL must return an XML document with Play, Speak, and/or Wait elements only. All other elements are ignored.

This audio is played to customers while they’re on hold. Sets the Customer Hold Music URL property of the MPC resource.

Default is Plivo’s default hold music.

If the URL is not reachable or does not return a valid XML document, no music will be played.
customer_hold_music_method
string
The HTTP verb that should be used to invoke the URL configured as customer_hold_music_url.

Allowed values: GET, POST
Defaults to GET.
record
boolean
Indicates whether the MPC should be recorded. Recording will be initiated the first time a participant joins the MPC with record set to true.

Another participant joining with record set to false will not stop the recording. Note: Supervisor’s voice will be present in the recording regardless of whether coach mode is on or off.

Defaults to false.
record_file_format
string
Specifies the audio format for the recording.

Allowed values: mp3, wav
Defaults to mp3.
recording_callback_url
string
The URL to which the MPC recording events are to be posted.
recording_callback_method
string
The HTTP verb that should be used to invoke the URL configured as recording_callback_url.

Allowed values: GET, POST
Defaults to POST.
record_min_member_count
string
Starts MPC recording when count is reached. Applies only when record is set to true in the MultiPartyCall element.

Allowed values: 1, 2
Defaults to 1.

When set to 1, recording will start as soon as one member has entered the MPC.

When set to 2, recording will start only when two members have joined the MPC. Recording will not start for a single member in MPC even if record is set to true in the MultiPartyCall element.
record_participant_track
Boolean
Indicates whether single-track or participant-level recording will be initiated when the participant joins the MPC bridge. The generated recording file will contain only the audio of the specified participant.

Default: false
status_callback_url
string
The URL to which MPC status change events should be sent.
status_callback_method
string
The HTTP verb that should be used to invoke the URL configured as status_callback_url.

Allowed values: GET, POST
Defaults to POST.
status_callback_events
string
Controls which of the following events, generated over the course of the multiparty call, should be pushed to the specified status_callback_url:

- MPCInitialized
- MPCStart
- MPCEnd
- ParticipantJoin
- ParticipantExit
- ParticipantMute
- ParticipantUnmute
- ParticipantHold
- ParticipantUnhold
- ParticipantSpeakStart
- ParticipantSpeakStop
- ParticipantCoachModeStart
- ParticipantCoachModeStop
- ParticipantDigitInput
- AddParticipantByAPIActionInitiated
- AddParticipantByAPIActionCompleted

Allowed values: mpc-state-changes, participant-state-changes, participant-digit-input-events, participant-speak-events, add-participant-api-events, participant-audio-events (in any order, with multiple values separated by commas)

Note
- When mpc-state-changes is included, events for MPCInitialized, MPCStart, and MPCEnd are sent.
- When participant-state-changes is included, events for ParticipantJoin, ParticipantExit, ParticipantMute,ParticipantUnmute, ParticipantHold, ParticipantUnhold, ParticipantCoachModeStart, ParticipantCoachModeStop are sent.
- When participant-speak-events is included, events for ParticipantSpeakStart and ParticipantSpeakStop are sent whenever any participant begins or stops speaking.
- When participant-digit-input-events is included, ParticipantDigitInput events are sent whenever any participant provides a DTMF input.
- When add-participant-api-events is included, AddParticipantByAPIActionInitiated and AddParticipantByAPIActionCompleted events are sent when an Add Participant By API Action is carried out.
- When participant-audio-events is included, the following callbacks will be posted to “status_callback_url”

ParticipantAudioPlayed : When audio starts playing for a participant

ParticipantAudioStopped : When audio stops playing for a participant

Defaults to mpc-state-changes,participant-state-changes.
stay_alone
boolean
Indicates whether a participant should be removed from the call if they are the only member remaining in the call.

Allowed values: true, false
Defaults to false.
coach_mode
boolean
Only applies to participants with the role Supervisor.

Defaults to true (by default, supervisors are in coach mode).
mute
boolean
Indicates whether the participant should join muted or not.

Allowed values: true, false
Defaults to false.
hold
boolean
Indicates whether the participant should join on hold or not.

Allowed values: true, false
Defaults to false.
start_mpc_on_enter
boolean
Indicates whether the MPC should start, if not already started, when this participant joins.

Allowed values: true, false
Defaults to true.
end_mpc_on_exit
boolean
Indicates whether the MPC should be ended when this participant exits the call.

Allowed values: true, false
Defaults to false.
enter_sound
string
The sound to play on the bridge when the participant enters the MPC. Note that enter_sound should never be played for supervisors entering when coach mode is set to true.

Allowed values: none, beep:1, beep:2, URL that returns an XML document with Play, Speak, and/or Wait elements only
Defaults to beep:1.
enter_sound_method
string
The HTTP verb that should be used to invoke the URL configured as enter_sound.

Allowed values: GET, POST
Defaults to GET.
exit_sound
string
The sound to play when the participant exits the MPC.

This sound should be played even if the call is hung up while in MPC.

Note that exit_sound should never be played for supervisors exiting with coach mode set to true.

Allowed values: none, beep:1, beep:2, URL that returns an XML document with Play, Speak, and/or Wait elements only
Defaults to beep:2.
exit_sound_method
string
The HTTP verb that should be used to invoke the URL configured as exit_sound.

Allowed values: GET, POST
Defaults to GET.
on_exit_action_url
string
Action URL invoked when this participant exits the MPC. If the participant call hangs up while in the MPC or if the call has been transferred to another XML document, then a request to this URL will not be invoked.

If onExitActionUrl is provided, an XML document to control the flow of the call from here on is expected in the response.
on_exit_action_method
string
The HTTP verb that should be used to invoke the URL configured as on_exit_action_url.

Allowed values: GET, POST
Defaults to POST.
relay_dtmf_inputs
boolean
Indicates whether DTMF inputs pressed by one of the participants should be transmitted to other participants on the MPC.

Allowed values: true, false
Defaults to false.
sip_headers
string
List of SIP headers in the form of key=value pairs, separated by commas.

For example, head1=val1,head2=val2,head3=val3,…,headN=valN.

The SIP headers specified are automatically prefixed with “X-PH-” and these headers will be present for all the HTTP requests that are being made.

Only [A-Z], [a-z], and [0-9] characters are allowed for SIP header key names and values, so that you can URL-encode the values.

Valid values for SIP header keys and values are integers and uppercase and lowercase letters.

Note

For Multiple “to” numbers “sip_headers” must be delimited by ”<” — for example sip_headers=key1=value1<key2=value2<key3=value3.

List of events and parameters sent to the status_callback_url

Refer to status_callback_events for the events that are sent to status_callback_url: This information is sent to the URL when an event is triggered:
ArgumentDescription
DigitInput
string
A list of digits pressed by the participant.
EventName
string
Event that triggered this notification. This parameter has values from the events list.
EventTimestamp
string
Timestamp at which the event occurred.Format: YYYY-MM-DD HH:mm:ss+|-hh:mm
MPCBilledAmount
string
Amount charged for this call, in USD. This value is null if the MPC has not ended.
MPCBilledDuration
string
Duration in seconds for which the MPC was billed. This value is null if the MPC has not ended.
MPCCreationTime
string
Timestamp at which the MPC was created. Format: YYYY-MM-DD HH:mm:ss+|-hh:mm
MPCDuration
string
Total duration in seconds of the MPC.This value is null if the MPC has not ended.
MPCEndTime
string
Timestamp at which the MPC ended.Format: YYYY-MM-DD HH:mm:ss+|-hh:mm
MPCName
string
Friendly name provided during the creation of the MPC.
MPCStartTime
string
Timestamp at which the MPC was started. Format: YYYY-MM-DD HH:mm:ss+|-hh:mm
MPCTerminationCause
string
Reason for MPC termination. Refer to our list of termination causes and sources. This value is null if the MPC has not ended.
MPCTerminationCauseCode
string
A unique integer code for the termination cause. Refer to our list of termination causes and sources. This value is null if the MPC has not ended.
MPCUUID
string
Unique ID of the multiparty call.
MemberAddress
string
Phone number or the endpoint username of the participant added to the MPC.
MemberID
string
Unique identifier of the participant whose event triggered this callback in the MPC.
ParticipantCallDirection
string
Indicates the direction of the call (inbound or outbound) through which the participant was added to the MPC.
ParticipantCallFrom
string
Phone number or the endpoint username of the participant that added the respective participant to MPC.
ParticipantCallTo
string
Phone number or the endpoint username of the participant added to the MPC.
ParticipantCallUUID
string
Call UUID of the respective participant’s call leg.
ParticipantCoachMode
string
Indicates whether the Participant is in coach mode. Allowed values: true, false
ParticipantExitCause
string
Cause of the participant’s termination from the MPC.
ParticipantExitTime
string
Timestamp at which the participant was terminated from the MPC. Format: YYYY-MM-DD HH:mm:ss+|-hh:mm
ParticipantJoinTime
string
Timestamp at which the participant was added to the MPC. Format: YYYY-MM-DD HH:mm:ss+|-hh:mm
ParticipantRole
string
Identifies the role of the participant in the MPC. Can be be one of: Agent, Supervisor, Customer
SequenceNumber
string
Indicates the sequence of the callback. Helpful to sort the callback events posted to the status_callback_url.
STIRVerification
string

For outbound calls : Gives details about the attestation assigned to the call by Plivo.

For inbound calls : Gives details about the attestation received on the inbound call to your Plivo phone number.

Possible values:

  • Verified means the call is from a verified caller who has authorized access to the customer’s caller ID, and hence should be treated with confidence. Verified is equivalent to attestation level A.
  • Not Verified means that, for this call, either the caller is not verified, or it’s uncertain whether they have access to the caller ID used, or both. Not Verified means the call received attestation level B or C.
  • Not Applicable means STIR/SHAKEN doesn’t apply to this call, as would be the case if a call is not addressed to a US number or if it’s a cloud call (WebRTC or SIP).

Read more about STIR/SHAKEN.

List of events and parameters sent to the call_status_callback_url

These events are sent to this URL:
  • Initiated
  • Ringing
  • Answered
  • Hangup
This information is sent to the URL when an event is triggered:
ArgumentDescription
AnswerTime
string
Timestamp at which the participant entered the MPC. Format: YYYY-MM-DD HH:mm:ss+|-hh:mm
This value is null for Initiated and Ringing events.
BilledDuration
string
Duration in seconds for which the MPC was billed.
This value is null if the participant is still in a live MPC.
CallUUID
string
UUID of the call resource. Note that there can be more than one participant entry for the same call UUID if a participant entered and exited the MPC more than once.
Duration
string
Duration in seconds for which the participant was part of the MPC. This value is null if the participant is still in a live MPC.
EventName
string
Event that triggered this notification. This parameter may have the values Initiated, Ringing, Answered, Hangup.
From
string
The “from” number that’s used as the caller ID to initiate the call to add the participant to the MPC.
HangupTime
string
Timestamp at which the member left the MPC. Format: YYYY-MM-DD HH:mm:ss+|-hh:mm
This value is null if the participant is still in a live MPC.
InitiationTime
string
Timestamp at which the member joined the MPC. Format: YYYY-MM-DD HH:mm:ss+|-hh:mm
MPCUUID
string
Unique ID of the MPC.
PlivoHangupCause
string
Reason for the MPC termination. Refer to our list of hangup causes and sources.

This value is null if the participant is still in a live MPC.
PlivoHangupCauseCode
string
A unique integer code for the termination cause. Refer to our list of hangup causes and sources. This value is null if the participant is still in a live MPC.
PlivoHangupSource
string
Entity that triggered the call hangup. Possible hangup sources are: Caller, Callee, Plivo, API Request, Answer XML, Error, and Unknown. Refer to our list of hangup causes and sources.
Rate
string
Per-minute rate charged based on the destination number.
RingTime
string
Duration in seconds for which the destination was ringing before the call was answered.
To
string
Destination called during the call.
TotalAmount
string
Total amount charged to the customer’s account for the MPC participant. This value is null if the participant is still in a live MPC.

List of events and parameters sent to the recording_callback_url

These events are generated:
  • MPCRecordingInitiated
  • MPCRecordingPaused
  • MPCRecordingResumed
  • MPCRecordingCompleted
  • MPCRecordingFailed
This information is sent to the URL when an event is triggered:
ArgumentDescription
EventName
string
Event that triggered this notification. This parameter will have one of the values from the list of events above.
EventTimestamp
string
Timestamp at which the event occurred.
Format: YYYY-MM-DD HH:mm:ss+|-hh:mm
MPCName
string
Friendly name provided during the creation of the MPC.
MPCUUID
string
Unique ID of the MPC.
RecordingDuration
string
Duration of the recording in seconds.
RecordingEndTime
string
Timestamp at which the recording ended.
Format: YYYY-MM-DD HH:mm:ss+|-hh:mm
RecordingFormat
string
Format of the recording.
RecordingResourceURL
string
Resource URL of the recording file. You can use this URL to fetch the recording details later.
RecordingStartTime
string
Timestamp at which the recording started.
Format: YYYY-MM-DD HH:mm:ss+|-hh:mm
RecordingURL
string
Complete path to the recorded file URL.
RecordingUUID
string
Unique identifier to identify the file.
SequenceNumber
string
Indicates the sequence of the callback. Helpful to sort the callback events posted to the recording_callback_url.

Returns

Returns a Participant object.
import plivo

client = plivo.RestClient(auth_id="<auth_id>", auth_token="<auth_token>")

call_params = {
    'role': "Agent",
    'start_mpc_on_enter': True,
    'from_': "<caller_id>", # Caller ID for the outbound call
    'to_': "<destination_number>", # The destination phone number or endpoint username of the participant to be added
    "enter_sound": "none"
}
response = client.multi_party_calls.add_participant(friendly_name="testmpc", **call_params)
print(response)

Response

The API response differs depending on whether this API is initiated to add participants through a new call or a call transfer. If new call(s): ToNum = toNumber1<toNumber2 FromNum = fromNumber
{
   "api_id":"bfe372c0-b451-11ea-815a-1094bbeb5c2c",
   "calls":[
  {
     "to":"toNumber1",
     "from":"fromNumber",
     "call_uuid":"0b7b4242-8ee8-4872-b447-81b4ce972eae"
  },
  {
     "to":"toNumber2",
     "from":"fromNumber",
     "call_uuid":"67c882e3-833b-4eb8-bdbc-6efcb806938a"
  }
   ],
   "message":"add participant action initiated",
   "request_uuid":"8420cdb1-f1d8-44a4-8c2a-556d156f1ffa"
}
For a single toNumber only one object is inside the calls list. If existing call being transferred: CallUUID = 0b7b4242-8ee8-4872-b447-81b4ce972eae
{
   "api_id":"bfe372c0-b451-11ea-815a-1094bbeb5c2c",
   "calls":[
  {
     "to":"<to_number_of_given_callUUID>",
     "from": "<from_number_of_given_callUUID>",
     "call_uuid":"67c882e3-833b-4eb8-bdbc-6efcb806938a"
  }
   ],
   "message":"add participant action initiated",
   "request_uuid":"8420cdb1-f1d8-44a4-8c2a-556d156f1ffa"
}
For queued action, the message says “add participant action queued.”