Add a participant to a multiparty call using API

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:

Using the <MultiPartyCall> element in the Answer URL
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

Argument	Description
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:

Argument	Description
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:

Argument	Description
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:

Argument	Description
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.”

Request

Response

Call

Multiparty call

Conference

Audio Stream

Verified Caller ID

Endpoint

Recording

Add a participant to a multiparty call using API

API Endpoint

Add a participant to a multiparty call using API

Arguments

List of events and parameters sent to the status_callback_url

List of events and parameters sent to the call_status_callback_url

List of events and parameters sent to the recording_callback_url

Returns

Response

Request

Response

Call

Multiparty call

Conference

Audio Stream

Verified Caller ID

Endpoint

Recording

​API Endpoint

​Add a participant to a multiparty call using API

​Arguments

​List of events and parameters sent to the status_callback_url

​List of events and parameters sent to the call_status_callback_url

​List of events and parameters sent to the recording_callback_url

​Returns

​Response

API Endpoint

Add a participant to a multiparty call using API

Arguments

List of events and parameters sent to the status_callback_url

List of events and parameters sent to the call_status_callback_url

List of events and parameters sent to the recording_callback_url

Returns

Response