<Response>
   <MultiPartyCall role="customer" maxDuration="10000" maxParticipants="10" waitMusicMethod="GET" agentHoldMusicMethod="GET" customerHoldMusicMethod="GET" record="false" recordFileFormat="mp3" recordingCallbackMethod="GET" statusCallbackEvents="mpc-state-changes,participant-state-changes" statusCallbackMethod="POST" stayAlone="false" coachMode="true" mute="false" hold="false" startMpcOnEnter="true" endMpcOnExit="false" enterSound="beep:1" enterSoundMethod="GET" exitSound="beep:2" exitSoundMethod="GET" onExitActionMethod="POST" relayDTMFInputs="false">mpc_name</MultiPartyCall>
</Response>

The MultiPartyCall element can add a participant to an ongoing multiparty call (MPC) or start a new multiparty call and to add a participant to it.

Note: Some of this element’s attributes apply at the MPC level, some at the participant level. For example, maxDuration and maxParticipants set the MPC’s maximum duration and maximum allowed participants, while role and coachMode update a specific participant.

​
Attributes

maxDuration
MPC level
integer

Sets 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).

maxParticipants
MPC level
integer

Sets the Max Participants property of the MPC resource.

Allowed values: 2 to 10
Defaults to 10.

waitMusicUrl
MPC level
string

The URL of an audio file to be played in a loop to participants waiting for the MPC to begin.

The URL must return an XML document with Play, Speak, and/or Wait elements only. All other elements are ignored.

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.

waitMusicMethod
MPC level
string

The HTTP verb used to invoke the URL configured as waitMusicUrl.

Allowed values: GET, POST
Defaults to GET.

agentHoldMusicUrl
MPC level
string

The URL of an audio file to be played to agents while they’re on hold. Sets the Agent Hold Music URL property of the MPC resource.

The URL must return an XML document with Play, Speak, and/or Wait elements only. All other elements are ignored.

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.

agentHoldMusicMethod
MPC level
string

The HTTP verb used to invoke the URL configured as agentHoldMusicUrl.

Allowed values: GET, POST
Defaults to GET.

customerHoldMusicUrl
MPC level
string

The URL of an audio file to be played to customers while they’re on hold. Sets the Customer Hold Music URL property of the MPC resource.

The URL must return an XML document with Play, Speak, and/or Wait elements only. All other elements are ignored.

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.

customerHoldMusicMethod
MPC level
string

The HTTP verb that should be used to invoke the URL configured as customerHoldMusicUrl.

Allowed values: GET, POST
Defaults to GET.

record
MPC level
boolean

Indicates whether the MPC should be recorded. Recording is 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.

recordFileFormat
MPC level
string

Specifies the audio format for the recording.

Allowed values: mp3, wav
Defaults to mp3.

recordingCallbackUrl
MPC level
string

The URL to which MPC recording events are posted.

recordingCallbackMethod
MPC level
string

The HTTP verb that should be used to invoke the URL configured as recordingCallbackUrl.

Allowed values: GET, POST
Defaults to POST.

recordMinMemberCount
MPC level
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.

recordParticipantTrack
Boolean

Indicates whether single-track or participant-level recording will be initiated when the participant joins the MPC bridge.

Default: false

statusCallbackUrl
MPC level
string

The URL to which MPC status change events are sent.

statusCallbackMethod
MPC level
string

The HTTP verb that should be used to invoke the URL configured as statusCallbackUrl.

Allowed values: GET, POST
Defaults to POST.

statusCallbackEvents
MPC level
string

This attribute controls which of these 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, separated by commas)

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

stayAlone
Participant level
boolean

Indicates whether a participant should be removed from the call if they’re the only member remaining in the call.

Allowed values: true, false
Defaults to false.

role
Participant level
string

Must be one of Agent, Supervisor, or Customer.

coachMode
Participant level
boolean

Only applies to participants with the role Supervisor.

Defaults to true (by default, supervisors are in coach mode).

mute
Participant level
boolean

Indicates whether the participant should join muted.

Allowed values: true, false
Defaults to false.

hold
Participant level
boolean

Indicates whether the participant should join on hold or not.

Allowed values: true, false
Defaults to false.

startMpcOnEnter
Participant level
boolean

Indicates whether the MPC should start, if not already started, when this participant joins the call.

Allowed values: true, false
Defaults to true.

endMpcOnExit
Participant level
boolean

Indicates whether the MPC should be ended when this participant exits the call.

Allowed values: true, false
Defaults to false.

enterSound
Participant level
string

The sound to play on the bridge when the participant enters the MPC. Note that enterSound 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.

enterSoundMethod
Participant level
string

The HTTP verb that should be used to invoke the URL configured as enterSound.

Allowed values: GET, POST
Defaults to GET.

exitSound
Participant level
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 an MPC.

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

exitSoundMethod
Participant level
string

The HTTP verb that should be used to invoke the URL configured as exitSound.

Allowed values: GET, POST
Defaults to GET.

onExitActionUrl
Participant level
string

Action URL invoked when this participant exits the MPC. If the participant call hangs up while in the MPC or if the call is 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.

onExitActionMethod
Participant level
string

The HTTP verb that should be used to invoke the URL configured as onExitActionUrl.

Allowed values: GET, POST
Defaults to POST.

relayDTMFInputs
Participant level
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.

​
List of events and parameters sent to the statusCallbackUrl

This information is sent to statusCallbackUrl when an event is triggered:

DigitInput
string		A list of digits pressed by the participant.
EventName
string		Event that triggered this notification. This parameter will have values from the above 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 hangup 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 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 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.

Allowed values: 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 here.

​
List of events and parameters sent to the recordingCallbackUrl

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 multiparty call.
RecordingDuration
string		Duration of 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.

Allowed values: mp3, wav

RecordingResourceURL
string		Resource URL of the recording file. You can use this URL to fetch 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 recording file URL.
RecordingUUID
string		Unique identifier to identify the recording file.
SequenceNumber
string		Indicates the sequence of the callback. Helpful to sort the callback events posted to the recording_callback_url.

​
Parameters sent to the onExitActionUrl

MPCUUIDUnique ID of the multiparty call.
MPCFriendlyNameFriendly name provided during the creation of the MPC.
MemberIDUnique identifier to identify each participant in the MPC.
ParticipantCallUUIDCall UUID of the participant’s call leg.
ParticipantJoinTimeTimestamp at which the participant was added to the MPC. Format: YYYY-MM-DD HH:mm:ss+|-hh:mm
ParticipantEndTimeTimestamp at which the participant was terminated from the MPC. Format: YYYY-MM-DD HH:mm:ss+|-hh:mm
ParticipantRole

Identifies the role of the participant in the MPC.

Allowed values: Agent, Supervisor, Customer

The first caller to execute this XML initializes and starts the multiparty call named My MPC. The next caller to execute this XML joins the same MPC.

Python
from plivo import plivoxml

response = plivoxml.ResponseElement()
response.add(
    plivoxml.MultiPartyCallElement(
        content="mpc_name", role="customer", max_duration=10000
    )
)

print(response.to_string())
Ruby
require 'rubygems'
require 'plivo'
include Plivo::XML
include Plivo::Exceptions

begin
  response = Response.new
  response.addMultiPartyCall(
          'mpc_name',
          role: 'Agent',
          maxDuration: 10000)
  xml = PlivoXML.new(response)
  puts xml.to_xml
rescue PlivoXMLError => e
  puts 'Exception: ' + e.message
end
Node
var plivo = require('plivo');

var response = plivo.Response();

response.addMultiPartyCall('mpc_name', {
    role: 'customer',
    maxDuration: 10000
});

console.log(response.toXML());
PHP
<?php
require 'vendor/autoload.php';

use Plivo\Exceptions\PlivoXMLException;
use Plivo\Util\MPCUtils;
use Plivo\XML\Response;

$response = new Response();

$response->addMultiPartyCall("mpc_name", ["role" => "Customer", "maxDuration" => 10000]);

Header('Content-type: text/xml');
echo ($response->toXML());
Java
import com.plivo.api.exceptions.PlivoValidationException;
import com.plivo.api.exceptions.PlivoXmlException;
import com.plivo.api.models.multipartycall.MultiPartyCallUtils;
import com.plivo.api.xml.MultiPartyCall;
import com.plivo.api.xml.Response;

public class Test {
    public static void main(String[] args) throws PlivoValidationException, PlivoXmlException {
        Response resp = new Response();
        resp.children(new MultiPartyCall("mpc_name", MultiPartyCallUtils.customer).maxDuration(10000));
        System.out.println(resp.toXmlString());
    }
}
.NET
using System;
using Plivo.Exception;
using System.Collections.Generic;

namespace PlivoExamples {
  class Program {
    static void Main(string[] args) {
      try {
        Plivo.XML.Response resp = new Plivo.XML.Response();
        resp.AddMultiPartyCall("mpc_name",
          new Dictionary < string, string > () {
            {"role","customer"},
            {"maxDuration","10000"}
          });
        Console.WriteLine(resp.ToString());
      } catch (PlivoRestException e) {
        Console.WriteLine("Exception: " + e.Message);
      }

    }
  }
}
Go
package main

import "github.com/plivo/plivo-go/v7/xml"

func main() {
    response: = xml.ResponseElement {
        Contents: [] interface {} {

            new(xml.MultiPartyCallElement).
            SetRole("customer").
            SetMaxDuration(10000).
            SetContents("mpc_name"),
        },
    }
    print(response.String())
}
cURL
<Response>
   <MultiPartyCall role="customer" maxDuration="10000" maxParticipants="10" waitMusicMethod="GET" agentHoldMusicMethod="GET" customerHoldMusicMethod="GET" record="false" recordFileFormat="mp3" recordingCallbackMethod="GET" statusCallbackEvents="mpc-state-changes,participant-state-changes" statusCallbackMethod="POST" stayAlone="false" coachMode="true" mute="false" hold="false" startMpcOnEnter="true" endMpcOnExit="false" enterSound="beep:1" enterSoundMethod="GET" exitSound="beep:2" exitSoundMethod="GET" onExitActionMethod="POST" relayDTMFInputs="false">mpc_name</MultiPartyCall>
</Response>