The MultiPartyCall Element Beta

    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 the attributes of this element apply at the MPC level, some at the participant level. For example, maxDuration and maxParticipants are attributes used to set the maximum duration and maximum allowed participants of an MPC, while role and coachMode are at the participant level, as these are attributes used to update a specific participant in the MPC.

    Attributes

    maxDurationMPC levelinteger

    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).
    maxParticipantsMPC levelinteger

    The maximum number of participants. Sets the Max Participants property of the MPC resource.

    • Allowed values: 2 to 10.
    • Defaults to 10.
    waitMusicUrlMPC levelstring

    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.

    Note: If the URL is not reachable or does not return a valid XML document, no music will be played.

    waitMusicMethodMPC levelstring

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

    • Allowed values: GET, POST.
    • Defaults to GET.
    agentHoldMusicUrlMPC levelstring

    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.

    Note: If the URL is not reachable or does not return a valid XML document, no music will be played.

    agentHoldMusicMethodMPC levelstring

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

    • Allowed values: GET, POST.
    • Defaults to GET.
    customerHoldMusicUrlMPC levelstring

    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.

    Note: If the URL is not reachable or does not return a valid XML document, no music will be played.

    customerHoldMusicMethodMPC levelstring

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

    • Allowed values: GET, POST.
    • Defaults to GET.
    recordMPC levelboolean

    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.

    recordFileFormatMPC levelstring

    Specifies the audio format for the recording.

    • Allowed values: mp3, wav.
    • Defaults to mp3.
    recordingCallbackUrlMPC levelstring

    The URL to which the MPC recording events are to be posted.

    recordingCallbackMethodMPC levelstring

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

    • Allowed values: GET, POST.
    • Defaults to POST.
    statusCallbackUrlMPC levelstring

    The URL to which MPC status change events should be sent.

    statusCallbackMethodMPC levelstring

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

    • Allowed values: GET, POST.
    • Defaults to POST.
    statusCallbackEventsMPC levelstring

    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".
    stayAloneParticipant levelboolean

    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.
    roleParticipant levelstring

    Must be one of:

    • Agent
    • Supervisor
    • Customer
    coachModeParticipant levelboolean

    Only applies to participants with the role Supervisor.

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

    muteParticipant levelboolean

    Whether the participant should join muted or not.

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

    Whether the participant should join on hold or not.

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

    Whether the MPC should start, if not already started, when this participant joins.

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

    Whether the MPC should be ended when this participant exits the call.

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

    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.
    enterSoundMethodParticipant levelstring

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

    • Allowed values: GET, POST.
    • Defaults to GET.
    exitSoundParticipant levelstring

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

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

    • Allowed values: GET, POST.
    • Defaults to GET.
    onExitActionUrlParticipant levelstring

    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.

    onExitActionMethodParticipant levelstring

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

    • Allowed values: GET, POST.
    • Defaults to POST.
    relayDTMFInputsParticipant levelboolean

    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

    status_callback_events for the events that are sent to statusCallbackUrl:

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

    DigitInputstringA list of digits pressed by the participant.
    EventNamestringEvent that triggered this notification. This parameter will have values from the above events list.
    EventTimestampstringTimestamp at which the respective event occurred.Format: YYYY-MM-DD HH:mm:ss+|-hh:mm
    MPCBilledAmountstringAmount charged for this call, in USD. This value is null if the MPC has not ended.
    MPCBilledDurationstringDuration in seconds for which the MPC was billed. This value is null if the MPC has not ended.
    MPCCreationTimestringTimestamp at which the MPC was created. Format: YYYY-MM-DD HH:mm:ss+|-hh:mm
    MPCDurationstringTotal duration in seconds of the MPC.This value is null if the MPC has not ended.
    MPCEndTimestringTimestamp at which the MPC ended.Format: YYYY-MM-DD HH:mm:ss+|-hh:mm
    MPCNamestringFriendly name provided during the creation of the MPC.
    MPCStartTimestringTimestamp at which the MPC was started. Format: YYYY-MM-DD HH:mm:ss+|-hh:mm
    MPCTerminationCausestringReason 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.
    MPCTerminationCauseCodestringA 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.
    MPCUUIDstringUnique ID of the Multiparty Call.
    MemberAddressstringPhone number or the endpoint username of the participant added to the MPC.
    MemberIDstringUnique identifier of the participant whose event triggered this callback in the MPC.
    ParticipantCallDirectionstringIndicates the direction of the call (inbound or outbound) through which the participant was added to the MPC.
    ParticipantCallFromstringPhone number or the endpoint username of the participant that added the respective participant to MPC.
    ParticipantCallTostringPhone number or the endpoint username of the participant added to the MPC.
    ParticipantCallUUIDstringCall UUID of the respective participant’s call leg.
    ParticipantCoachModestringIndicates whether the Participant is in coach mode. Allowed values: true, false
    ParticipantExitCausestringCause of the participant’s termination from the MPC.
    ParticipantExitTimestringTimestamp at which the participant was terminated from the MPC.Format: YYYY-MM-DD HH:mm:ss+|-hh:mm
    ParticipantJoinTimestringTimestamp at which the participant was added to the MPC.Format: YYYY-MM-DD HH:mm:ss+|-hh:mm
    ParticipantRolestringIdentifies the role of the participant in the MPC. Can be be one of:

    Agent

    Supervisor

    Customer

    SequenceNumberstringIndicates 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 recordingCallbackUrl

    These events are generated:

    • MPCRecordingInitiated
    • MPCRecordingPaused
    • MPCRecordingResumed
    • MPCRecordingCompleted
    • MPCRecordingFailed

    This information is sent to the URL when an event is triggered:

    EventNamestringEvent that triggered this notification. This parameter will have one of the values from the list of events above.
    EventTimestampstringTimestamp at which the event occurred.

    Format: YYYY-MM-DD HH:mm:ss+|-hh:mm

    MPCNamestringFriendly name provided during the creation of the MPC.
    MPCUUIDstringUnique ID of the Multiparty call.
    RecordingDurationstringDuration of recording in seconds.
    RecordingEndTimestringTimestamp at which the recording ended.

    Format: YYYY-MM-DD HH:mm:ss+|-hh:mm

    RecordingFormatstringFormat of the recording.
    RecordingResourceURLstringResource URL of the recording file. You can use this URL to fetch the recording details later.
    RecordingStartTimestringTimestamp at which the recording started.

    Format: YYYY-MM-DD HH:mm:ss+|-hh:mm

    RecordingURLstringComplete path to the recorded file URL.
    RecordingUUIDstringUnique identifier to identify the file.
    SequenceNumberstringIndicates 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 respective 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

    ParticipantRoleIdentifies the role of the participant in the MPC.

    Can be be one of:

    • Agent
    • Supervisor
    • Customer

    The first caller to execute this XML joins the multiparty call “My MPC”. When the next caller executes this XML, the caller will join the same MPC.

    Response

    <Response>
      <MultiPartyCall>My MPC</MultiPartyCall>
    </Response>