Latest Legacy

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 — 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 examplesip_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:

   
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:

   
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:

   
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.

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_': "<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)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

require 'rubygems'
require 'plivo'
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":"<caller_id>",
    "to":"<destination_number>",
    "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': '<caller_id>', 'to': '<destination_number>' }).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" => "<caller_id>", "to" => "<destination_number>"]);
    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, "<caller_id>", Collections.singletonList("<destination_number>"))
                .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: "<caller_id>",
                to: "<destination_number>",
                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": "+12025551111","from": "+12025550000", "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/v7"
)

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: "<caller_id>",
        To: "<destination_number>"
    })
    if err != nil {
        panic(err)
    }
    fmt.Printf("Response: %#v\n", response)
}