Skip to navigation
Voice

Conference

View as MarkdownOpen in Claude

<Dial> verb’s <Conference> noun allows the connection to a named conference room. For example:

<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Dial>
    <Conference>Room 1234</Conference>
  </Dial>
</Response>

Noun attributes

beep
stringDefaults to true

Whether or not a sound is played when callers leave or enter a conference. See below for all possible values.

coach
string

Coach accepts a call SID of a call that is currently connected to an in-progress conference. Specifying a call SID that does not exist or is no longer connected to the conference will result in the call failing to the action URL and throwing a 13240 error.

emitCallQuality
booleanDefaults to false

When true, a participant-call-quality request with this participant’s audio statistics is sent to statusCallback when the participant leaves, if statistics are available. To receive it, include leave in statusCallbackEvent. See below for request parameters.

endConferenceOnExit
booleanDefaults to false

If a participant with endConferenceOnExit set to true leaves a conference, the conference terminates and all participants drop out of the call.

eventCallbackUrl
string

A URL for conference recording status requests, used only when recordingStatusCallback is not set. Requests to it are always POST. Takes effect only when record is record-from-start.

maxParticipants
integer

The maximum number of participants allowed in a named conference room.

muted
booleanDefaults to false

Whether or not a caller can speak in a conference.

record
stringDefaults to do-not-record

Can be used to record an entire <Conference>. record-from-start will begin recording the conference call once the first two participants join in on the call. Wait music is not recorded.

recordingStatusCallback
string

The recordingStatusCallback attribute takes in an absolute URL. SignalWire will make a GET or POST request to this URL when recording is accessible. See below for request parameters.

recordingStatusCallbackEvent
stringDefaults to completed

The recording status that triggers a request to recordingStatusCallback. Set a single lowercase value from the list below. A list of values, or a value not in that list, is treated as completed. A listed value written with capital letters, such as Completed, sends no request.

recordingStatusCallbackMethod
stringDefaults to POST

The type of HTTP request to use when requesting a recordingStatusCallback.

startConferenceOnEnter
booleanDefaults to true

The conference begins once a specific caller enters into the conference room, unless it has already started. If a participant joins and startConferenceOnEnter is false, that participant will hear background music and stay muted until a participant with startConferenceOnEnter set to true joins the call.

statusCallback
string

The URL to make requests to for each statusCallbackEvent event. The URL is set by the first participant to enter a conference. All other information provided by other participants will be ignored. See below for request parameters.

statusCallbackEvent
string

Which conference state changes will trigger a webhook to the URL provided in statusCallback. Specifies conference state changes. The first participant to join the named conference is able to manipulate and set events. All other changes made by other participants will be ignored. See below for all possible events. To specify multiple events, separate them with a space.

statusCallbackMethod
stringDefaults to POST

The type of HTTP request to use when requesting a statusCallback.

trim
stringDefaults to trim-silence

Whether or not silence in the beginning and end of recordings are removed.

waitMethod
stringDefaults to POST

Specifies whether the request to waitUrl is a GET or a POST.

waitUrl
string

URL for the music to play in the background while participants are waiting to enter a conference room. Only supports <Play>, <Pause>, and <Redirect>. If no waitUrl is provided, SignalWire will use its hold music.

Values for the beep attribute

The beep attribute has the following values:

ValueDescription
truePlays a beep when a caller leaves or enters a conference. The default value for beep.
falseDisables the beep when callers leave and enter conferences.
onEnterOnly plays a beep when a caller enters a conference.
onExitOnly plays a beep when a caller leaves a conference.

Events for the statusCallbackEvent attribute

The statusCallbackEvent attribute has the following events. Each one sends the StatusCallbackEvent values listed beside it. If you set statusCallback without statusCallbackEvent, no callbacks are sent.

EventDescriptionStatusCallbackEvent values sent
startThe conference has started as long as there are at least two people in the conference room and one of the participant’s startConferenceOnEnter is set to true.conference-start
endThe conference ends when the last participant in the call or a participant with endConferenceOnExit set to true leaves the call.conference-end
joinWhen a participant joins a conference.participant-join
leaveWhen a participant leaves a conference.participant-leave, plus participant-call-quality for a participant who joined with emitCallQuality set to true
muteWhen a participant has been muted or un-muted.participant-mute, participant-unmute
holdWhen a participant has been put on hold or put out of hold.participant-hold, participant-unhold
speakerWhen a participant has begun or stopped speaking.participant-speech-start, participant-speech-stop

Request parameters for the statusCallback URL

SignalWire sends the parameters below to your statusCallback URL, as a form-encoded POST body or, when statusCallbackMethod is GET, as query parameters. Every value is a string, so boolean parameters arrive as true or false. The full schema, with an example payload, is on the Conference status callback reference.

Which parameters are sent depends on the event:

Parameterconference-start, conference-endparticipant-join, -leave, -mute, -unmute, -hold, -unholdparticipant-speech-start, -speech-stopparticipant-call-quality
AccountSid, ConferenceSid, StatusCallbackEvent, TimestampYesYesYesYes
CallSidSent with no valueYesYesYes
FriendlyNameYesYesNoNo
Muted, HoldSent with no valueYesYesNo
EndConferenceOnExit, StartConferenceOnEnter, Coaching, CallSidToCoachNoYesYesNo
ReasonConferenceEnded, CallSidEndingConferenceconference-end onlyNoNoNo
AudioRttAvg, AudioRttMin, AudioRttMax, AudioOutJitterAvg, AudioOutJitterMin, AudioOutJitterMax, AudioOutLostNoNoNoYes; AudioOutJitterAvg only when RTCP (RTP Control Protocol) reports were received
AccountSid
string

The unique ID of the project the conference belongs to.

ConferenceSid
string

The unique identifier for the conference.

FriendlyName
string

The name of the conference. Not sent on participant-speech-start, participant-speech-stop, or participant-call-quality.

StatusCallbackEvent
string

The event that triggered the request: conference-start, conference-end, participant-join, participant-leave, participant-mute, participant-unmute, participant-hold, participant-unhold, participant-speech-start, participant-speech-stop, or participant-call-quality. participant-call-quality reports the audio statistics of a participant who joined with emitCallQuality set to true, and is sent when that participant leaves.

Timestamp
string

The timestamp, in RFC 2822 format, of when SignalWire processed the event.

CallSid
string

The unique identifier of the participant’s call. Has no value on conference-start and conference-end.

Muted
string

Whether the participant is muted: true or false. Has no value on conference-start and conference-end, and is not sent on participant-call-quality.

Hold
string

Whether the participant is on hold: true or false. Has no value on conference-start and conference-end, and is not sent on participant-call-quality.

EndConferenceOnExit
string

Whether the conference ends when this participant leaves: true or false. Sent on participant events except participant-call-quality.

StartConferenceOnEnter
string

Whether the conference starts when this participant joins: true or false. Sent on participant events except participant-call-quality.

Coaching
string

Whether the participant is coaching another call: true or false. Sent on every participant event except participant-call-quality, whether or not the participant joined with the coach attribute.

CallSidToCoach
string

The unique identifier of the call this participant is coaching. Sent on every participant event except participant-call-quality; has no value when the participant is not coaching.

ReasonConferenceEnded
string

Why the conference ended. Sent on conference-end only, and can be empty when no reason was recorded.

ValueMeaning
last-participant-leftThe last participant left.
last-participant-kickedThe last participant was removed from the conference.
participant-with-end-conference-on-exit-leftA participant with endConferenceOnExit set to true left.
participant-with-end-conference-on-exit-kickedA participant with endConferenceOnExit set to true was removed from the conference.
conference-ended-via-apiThe conference was ended through the REST API, by updating the conference with Status set to completed.
downSignalWire ended the conference after a service interruption.
staleSignalWire closed a conference that was still open but no longer active.
CallSidEndingConference
string

The unique identifier of the call whose departure ended the conference. Sent on conference-end only; has no value when the conference did not end because a participant left or was removed.

AudioRttAvg
number

The participant’s average audio round-trip time, in seconds. Sent on participant-call-quality only, as 0 when nothing was measured.

AudioRttMin
number

The participant’s minimum audio round-trip time, in seconds. Sent on participant-call-quality only, as 0 when nothing was measured.

AudioRttMax
number

The participant’s maximum audio round-trip time, in seconds. Sent on participant-call-quality only, as 0 when nothing was measured.

AudioOutJitterAvg
integer

The average jitter of the audio stream SignalWire sends to the participant. Measured in RTP timestamp units, not milliseconds: divide by the codec’s samples per millisecond (8 for PCMU and PCMA, 48 for Opus) to convert. Sent on participant-call-quality only, and omitted when no RTCP reports were received from the participant.

AudioOutJitterMin
integer

The minimum jitter of the audio stream SignalWire sends to the participant. Measured in RTP timestamp units, not milliseconds: divide by the codec’s samples per millisecond (8 for PCMU and PCMA, 48 for Opus) to convert. Sent on participant-call-quality only, as 0 when no RTCP reports were received from the participant.

AudioOutJitterMax
integer

The maximum jitter of the audio stream SignalWire sends to the participant. Measured in RTP timestamp units, not milliseconds: divide by the codec’s samples per millisecond (8 for PCMU and PCMA, 48 for Opus) to convert. Sent on participant-call-quality only, as 0 when no RTCP reports were received from the participant.

AudioOutLost
integer

The number of audio RTP packets SignalWire sent to the participant that were reported lost. Sent on participant-call-quality only, as 0 when nothing was measured.

Request parameters for the recordingStatusCallback URL

Conference recordings send the same parameters as call recordings, with ConferenceSid in place of CallSid. See the Recording status callback reference for every field.

Payload
{
  "AccountSid": "b3877c40-da60-4998-90ad-b792e98472af",
  "RecordingSid": "b3877c40-da60-4998-90ad-b792e984re01",
  "RecordingUrl": "https://example.signalwire.com/api/laml/2010-04-01/Accounts/b3877c40-da60-4998-90ad-b792e98472af/Recordings/b3877c40-da60-4998-90ad-b792e984re01",
  "RecordingStatus": "completed",
  "RecordingChannels": 1,
  "RecordingSource": "RecordVerb",
  "RecordingTrack": "both",
  "RecordingStartTime": "Thu, 04 Apr 2024 18:32:15 +0000",
  "Trim": "trim-silence"
}

Status values for the recordingStatusCallbackEvent attribute

The recordingStatusCallbackEvent attribute takes one of the following values. Each value sends only its own request, so in-progress alone sends no request when the recording completes.

ValueDescription
in-progressA request is sent when the recording begins.
completedA request is sent when the recording has completed and is accessible. The default value. If the recording captured no audio, no request is sent.
absentA request is sent only when SignalWire closes a recording that produced no file, such as after a service interruption. A recording that ends normally with no audio sends no request.

Examples

A simple conference call

<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Dial>
    <Conference>Room 1234</Conference>
  </Dial>
</Response>

The first participant would join the conference “Room 1234” and listen to wait music in the background until a second participant joins the conference. Once participants have joined the conference, the wait music comes to an end, a beep is played, and the conference call begins.

A moderated conference call

<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Dial>
    <Conference startConferenceOnEnter="false">
      moderated-conference-room
    </Conference>
  </Dial>
</Response>

You can set the startConferenceOnEnter to false so that a group of participants can join in the conference room but the conference cannot begin until the moderator has entered the call. As the participants wait for the conference to begin, hold music will be playing in the background.

Start a moderated conference call

<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Dial>
    <Conference startConferenceOnEnter="true" endConferenceOnExit="true">
      moderated-conference-room
    </Conference>
  </Dial>
</Response>

Now, since the moderator has joined in on the conference call, startConferenceOnEnter is set to true which means the conference can begin. All the participants that were waiting on hold will now be connected to the conference room; the hold music will come to an end and a beep notification will play indicating conference entrance. Once the moderator leaves the call, the conference will come to an end and all participants will be disconnected from the call.

Joining a conference call muted (Monitor)

<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Dial>
    <Conference muted="true">ConferenceRoom</Conference>
  </Dial>
</Response>

Participants who enter a conference call muted can hear the other participants in the call who are unmuted. However, the unmuted participants cannot hear the muted callers. Muting and unmuting can be enabled and disabled in real-time via a REST API.

Coaching a conference call

<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Dial>
    <Conference coach="AgentCallSid">
      Example-Room
    </Conference>
  </Dial>
</Response>

Recording a conference call

<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Dial>
    <Conference record="record-from-start"
                recordingStatusCallback="https://www.example.com/recording_update">
      ConferenceCall
    </Conference>
  </Dial>
</Response>

The recording of the conference call will begin when at least two participants join the conference room. A recordingStatusCallback will be sent when the recording is accessible.

Notes on usage

  • You can freely name the conference room to fit your preference. However, only callers within a project can join in on a named conference room. Callers from separate projects will not be able to connect to that same conference room.
  • You can customize the background music as callers are waiting to join a conference call
  • Conferences will not begin unless there are 2 or more parties present.

*Twilio and TwiML are trademarks of Twilio, Inc. SignalWire, Inc. and its products are not affiliated with or endorsed by Twilio, Inc.