Add a Participant to a Multiparty Call using API

    This method retrieves the details of a particular Multiparty Call Participant.

    API Endpoint

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

    A participant can be added to a Multiparty Call in two ways:

    1. Using the <MultiPartyCall> element in the Answer URL
    2. Using MultiPartyCall REST API

    Note: A new MultipartyCall is initiated if no ongoing MPC is found in the account (or subaccount) with the given friendly name.

    Arguments

      
    from Required — ConditionalThe “from” number to use as the caller ID for this outbound call.
    to Required — ConditionalA 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. 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 — ConditionalThe 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 a new MPC will be created and the participant will be added.
    call_status_callback_url stringThis URL is invoked by Plivo 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 stringThe 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 stringIf 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 stringRemote 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 stringHTTP verb that should be used to invoke the URL configured as confirm_key_sound_url.
    confirm_key_sound_method stringHTTP verb that should be used to invoke the URL configured as confirm_key_sound_url.

    • Allowed values: GET, POST.
    • Defaults to GET
    ring_timeout integerThe 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.
    max_duration integerSets the Max Duration (in seconds) property of the MPC resource. The MPC will end after this period.

    maxDuration 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 integerThe maximum number of participants. Sets the Max Participants property of the MPC resource.

    • Allowed values: 2 to 10.
    • Defaults to 10.
    wait_music_url stringRemote 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.

    Note: If the URL is not reachable or does not return a valid XML document, no music will be played.
    wait_music_method stringThe 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 stringRemote 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.

    Note: If the URL is not reachable or does not return a valid XML document, no music will be played.
    agent_hold_music_method stringThe 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 stringRemote 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.

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

    • Allowed values: GET, POST.
    • Defaults to GET.
    record booleanWhether 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 stringSpecifies the audio format for the recording.

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

    • Allowed values: GET, POST.
    • Defaults to POST.
    status_callback_url stringThe URL to which MPC status change events should be sent.
    status_callback_method stringThe 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
    Possible values: “mpc-state-changes, participant-state-changes, participant-digit-input-events, participant-speak-events, add-participant-api-events” (in any order). This attribute 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
    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.
    • Defaults to "mpc-state-changes, participant-state-changes".
    stay_alone booleanWhether 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.
    role stringMust be one of:

    • Agent
    • Supervisor
    • Customer
    coach_mode booleanOnly applies to participants with the role Supervisor.

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

    • Allowed values: true, false
    • Defaults to false.
    hold booleanWhether the participant should join on hold or not.

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

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

    • Allowed values: true, false
    • Defaults to false.
    enter_sound stringThe 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 stringThe HTTP verb that should be used to invoke the URL configured as enter_sound.

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

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

    Note that exit sound should never be played for supervisors entering 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 stringThe 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 stringAction 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 stringThe 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 booleanWhether DTMF inputs pressed by one of the participants should be transmitted to other participants on the MPC.

    • Allowed values:true, false.
    • Defaults to false.

    List of events and parameters sent to the status_callback_url

    Refer status_callback_events for the events that are sent to status_callback_url:

    Following information will be sent to the URL when an event is triggered:

      
    DigitInput stringA list of digits pressed by the participant.
    EventName stringEvent that triggered this notification. This parameter will have values from the above events list.
    EventTimestamp stringTimestamp at which the respective event occurred.Format: YYYY-MM-DD HH:mm:ss+|-hh:mm
    MPCBilledAmount stringAmount charged for this call, in USD. This value is null if the MPC has not ended.
    MPCBilledDuration stringDuration in seconds for which the MPC was billed. This value is null if the MPC has not ended.
    MPCCreationTime stringTimestamp at which the MPC was created. Format: YYYY-MM-DD HH:mm:ss+|-hh:mm
    MPCDuration stringTotal duration in seconds of the MPC.This value is null if the MPC has not ended.
    MPCEndTime stringTimestamp at which the MPC ended.Format: YYYY-MM-DD HH:mm:ss+|-hh:mm
    MPCName stringFriendly name provided during the creation of the MPC.
    MPCStartTime stringTimestamp at which the MPC was started. Format: YYYY-MM-DD HH:mm:ss+|-hh:mm
    MPCTerminationCause stringReason for MPC termination. Refer to this page for a comprehensive list of termination causes and sources. This value is null if the MPC has not ended.
    MPCTerminationCauseCode stringA unique integer code for the termination cause. Refer to this page for a comprehensive list of hangup causes and sources. This value is null if the MPC has not ended.
    MPCUUID stringUnique ID of the Multiparty Call.
    MemberAddress stringPhone number or the endpoint username of the participant added to the MPC.
    MemberID stringUnique identifier of the participant whose event triggered this callback in the MPC.
    ParticipantCallDirection stringIndicates the direction of the call (inbound or outbound) through which the participant was added to the MPC.
    ParticipantCallFrom stringPhone number or the endpoint username of the participant that added the respective participant to MPC.
    ParticipantCallTo stringPhone number or the endpoint username of the participant added to the MPC.
    ParticipantCallUUID stringCall UUID of the respective participant’s call leg.
    ParticipantCoachMode stringIndicates whether the Participant is in coach mode. Allowed values: true, false
    ParticipantExitCause stringCause of the participant’s termination from the MPC.
    ParticipantExitTime stringTimestamp at which the participant was terminated from the MPC.Format: YYYY-MM-DD HH:mm:ss+|-hh:mm
    ParticipantJoinTime stringTimestamp at which the participant was added to the MPC.Format: YYYY-MM-DD HH:mm:ss+|-hh:mm
    ParticipantRole stringIdentifies the role of the participant in the MPC. Can be be one of:
    Agent

    Supervisor

    Customer
    SequenceNumber stringIndicates the sequence of the callback. Helpful to sort the callback events posted to the status_callback_url.

    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:

      
    AnswerTime stringTimestamp 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 stringDuration in seconds for which the MPC was billed.
    This value is null if the participant is still in a live MPC.
    CallUUID stringUUID 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 stringDuration 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 stringEvent that triggered this notification. This parameter may have the values Initiated, Ringing, Answered, Hangup.
    From stringThe “from” number that is used as the caller ID to initiate the call to add the participant to the MPC.
    HangupTime stringTimestamp 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 stringTimestamp at which the member joined the MPC. Format: YYYY-MM-DD HH:mm:ss+|-hh:mm
    MPCName stringFriendly name provided during the creation of the MPC.
    MPCUUID stringUnique ID of the Multiparty Call.
    PlivoHangupCause stringReason for the MPC termination. Refer to this page for a comprehensive list of termination causes and sources.

    This value is null if the participant is still in a live MPC.
    MPCTerminationCauseCode stringA unique integer code for the termination cause. Refer to this page for a comprehensive list of hangup causes and sources. This value is null if the MPC has not ended.
    PlivoHangupCauseCode stringA unique integer code for the termination cause. Refer to this page for a comprehensive list of hangup causes and sources. This value is null if the participant is still in a live MPC.
    PlivoHangupSource stringEntity that triggered the call hangup. Possible hangup sources are: Caller, Callee, Plivo, API Request, Answer XML, Error, and Unknown. Refer to this page for a comprehensive list of hangup causes and sources.
    Rate stringPer-minute rate charged based on the destination number.
    RingTime stringDuration in seconds for which the destination was ringing before the call was answered.
    To stringDestination called during the call.
    TotalAmount stringTotal 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:

      
    EventName stringEvent that triggered this notification. This parameter will have one of the values from the list of events above.
    EventTimestamp stringTimestamp at which the event occurred.
    Format: YYYY-MM-DD HH:mm:ss+|-hh:mm
    MPCName stringFriendly name provided during the creation of the MPC.
    MPCUUID stringUnique ID of the Multiparty call.
    RecordingDuration stringDuration of recording in seconds.
    RecordingEndTime stringTimestamp at which the recording ended.
    Format: YYYY-MM-DD HH:mm:ss+|-hh:mm
    RecordingFormat stringFormat of the recording.
    RecordingResourceURL stringResource URL of the recording file. You can use this URL to fetch the recording details later.
    RecordingStartTime stringTimestamp at which the recording started.
    Format: YYYY-MM-DD HH:mm:ss+|-hh:mm
    RecordingURL stringComplete path to the recorded file URL.
    RecordingUUID stringUnique identifier to identify the file.
    SequenceNumber stringIndicates the sequence of the callback. Helpful to sort the callback events posted to the recording_callback_url.

    Returns

    Returns a Participant object.

    Response

    The API response will differ 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 there will be only one object 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 would say add participant action queued.

    Example Request

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    
    import plivo
    
    client = plivo.RestClient(auth_id="your_auth_id", auth_token="your_auth_token")
    
    call_params = {
        'role': "Agent",
        'start_mpc_on_enter': True,
        'from_': "+14156667777", # Caller ID for the outbound call
        'to_': "+14156667778", # The destination phone number or endpoint username of the participant that has to be added.
        "enter_sound": "none"
    }
    response = client.multi_party_calls.add_participant(friendly_name="testmpc", **call_params)
    print(response)
    
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    
    var plivo = require('plivo');
    
    (function main() {
        'use strict';
    
        var client = new plivo.Client("<auth_id>","<auth_token>");
        client.multiPartyCalls.addParticipant('Agent', { 'friendlyName': 'testmpc', 'from': '+14156667777', 'to': '+14156667778' }).then(function (response) {
            console.log(response);
        }, function (err) {
            console.error(err);
        });
    })();