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

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

    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

    Note: Plivo initiates a new multiparty call 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. 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 — 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 Plivo will create a new MPC and add the participant.
    role RequiredAllowed 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 'from' number.
    Character limit — 50 characters.

    call_status_callback_url stringPlivo 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 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 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 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.
     

    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.

    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 integerSets 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 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.

    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.

    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.

    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 booleanIndicates 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 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
    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 (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.

    Defaults to mpc-state-changes,participant-state-changes.

    stay_alone booleanIndicates 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 booleanOnly applies to participants with the role Supervisor.

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

    Allowed values: true, false
    Defaults to false.

    hold booleanIndicates whether the participant should join on hold or not.
     

    Allowed values: true, false
    Defaults to false.

    start_mpc_on_enter booleanIndicates whether the MPC should start, if not already started, when this participant joins.
     

    Allowed values: true, false
    Defaults to true.

    end_mpc_on_exit booleanIndicates whether 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 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 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 booleanIndicates 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.

    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:

      
    DigitInput stringA list of digits pressed by the participant.
    EventName stringEvent that triggered this notification. This parameter has values from the events list.
    EventTimestamp stringTimestamp at which the 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 our 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 our list of termination 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.
    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 here

    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’s 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
    MPCUUID stringUnique ID of the MPC.
    PlivoHangupCause stringReason 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 stringA 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 stringEntity 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 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 MPC.
    RecordingDuration stringDuration of the 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 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.”

    Example Request

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    
    import plivo
    
    client = plivo.RestClient(auth_id="<auth_id>", auth_token="<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
    13
    14
    15
    16
    17
    
    require "rubygems"
    require "/root/plivo-ruby/lib/plivo.rb"
    include Plivo
    include Plivo::Exceptions
    
    api = RestClient.new("<auth_id>","<auth_token>")
    begin
      response = api.multipartycalls.add_participant(
        "role":"agent",
        "friendly_name":"my_mpc",
        "from":"+14156667777",
        "to":"+14156667776",
        "start_mpc_on_enter":true)
      puts response
    rescue PlivoRESTError => e
      puts 'Exception: ' + e.message
    end
    
    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);
        });
    })();
    
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    
    <?php
    require 'vendor/autoload.php';
    
    use Plivo\RestClient;
    use Plivo\Exceptions\PlivoRestException;
    
    $client = new RestClient("<auth_id>", "<auth_token>");
    try
    {
        $response = $client
            ->multiPartyCalls
            ->addParticipant("agent", ["friendly_name" => "mpc_name", "from" => "+14156667777", "to" => "+14156667776"]);
        print_r($response);
    }
    catch(PlivoRestException $ex)
    {
        print_r($ex);
    }
    
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    
    package com.plivo.examples.multipartycall;
    
    import com.plivo.api.Plivo;
    import com.plivo.api.exceptions.PlivoRestException;
    import com.plivo.api.exceptions.PlivoValidationException;
    import com.plivo.api.models.call.Call;
    import com.plivo.api.models.call.CallCreateResponse;
    import com.plivo.api.models.multipartycall.MultiPartyCall;
    import com.plivo.api.models.multipartycall.MultiPartyCallParticipantAddResponse;
    import com.plivo.api.models.multipartycall.MultiPartyCallUtils;
    
    import java.io.IOException;
    import java.util.Arrays;
    import java.util.Collections;
    import java.util.concurrent.TimeUnit;
    
    class AddParticipant {
        public static void main(String[] args) throws IOException, PlivoRestException, PlivoValidationException {
            Plivo.init("<auth_id>", "<auth_token>");
            try {
                MultiPartyCallParticipantAddResponse resp = MultiPartyCall.addParticipant(MultiPartyCallUtils.friendlyName("myMPC"),
                        MultiPartyCallUtils.customer, "fromNumber", Collections.singletonList("toNumbers"))
                    .update();
    
                System.out.println(resp.getMessage());
            } catch (Exception e) {
                e.printStackTrace();
            }
        }
    }
    
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    
    using System;
    using Plivo;
    using Plivo.Exception;
    
    namespace PlivoExamples
    {
        class Program
        {
            static void Main(string[] args)
            {
                var api = new PlivoApi("<auth_id>", "<auth_token>");
    
                try
                {
                    var response = api.MultiPartyCall.AddParticipant(
                    friendlyName: "mpc_name",
                    from: "+14156667777",
                    to: "+14156667778",
                    role: "Agent"
                    );
                    Console.WriteLine(response);
                }
                catch (PlivoRestException e)
                {
                    Console.WriteLine("Exception: " + e.Message);
                }
    
            }
        }
    }
    
    1
    2
    3
    4
    
    curl -i --user AUTH_ID:AUTH_TOKEN \
        -H "Content-Type: application/json" \
        -d '{"to": "+15671234567","from": "+14151234567", "role": "Agent", "start_mpc_on_enter": true}' \
        https://api.plivo.com/v1/Account/{auth_id}/MultiPartyCall/name_{mpc_name}/Participant/
    
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    
    package main
    
    import (
        "fmt"
    
        "github.com/plivo/plivo-go"
    )
    
    func main() {
        client, err: = plivo.NewClient("<auth_id>", "<auth_token>", & plivo.ClientOptions {})
        if err != nil {
            panic(err)
        }
        response, err: = client.MultiPartyCall.AddParticipant(plivo.MultiPartyCallBasicParams {
            FriendlyName: "<mpc_name>"
        }, plivo.MultiPartyCallAddParticipantParams {
            Role: "Agent",
            From: "+14156667778",
            To: "+14156667777"
        })
        if err != nil {
            panic(err)
        }
        fmt.Printf("Response: %#v\n", response)
    }