Voice

Conference

View as Markdown

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

1<?xml version="1.0" encoding="UTF-8"?>
2<Response>
3  <Dial>
4    <Conference>Room 1234</Conference>
5  </Dial>
6</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.

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

The eventCallbackUrl attribute takes a URL as an argument and makes a POST request to it when a conference ends.

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 failed

Specifies recording status changes. To specify multiple values, separate them by a space. See below for details.

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:

EventDescription
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.
endThe conference ends when the last participant in the call or a participant with endConferenceOnExit set to true leaves the call.
joinWhen a participant joins a conference.
leaveWhen a participant leaves a conference.
muteWhen a participant has been muted or un-muted.
holdWhen a participant has been put on hold or put out of hold.
speakerWhen a participant has begun or stopped speaking.

Request parameters for the statusCallback URL

You can expect several parameters to be present in the request associated to the statusCallback URL. First, you have the Standard Request Parameters. Then, you also have the following specific parameters:

AccountSid
string

A unique identifier for the Account this call is associated with.

CallSid
string

A unique identifier for the call.

ConferenceSid
string

A unique identifier for the named Conference.

Duration
integer

The time, in seconds, of the conference call.

EndConferenceOnExit
string

When a participant has this set on true and they leave a call, conference ends.

EventName
string

The name of the event.

FriendlyName
string

Name of the conference.

Hold
string

Whether a participant is on hold or not.

Muted
string

Whether a participant is muted or not.

RecordingFileSize
string

The size of the recorded audio file.

RecordingUrl
string

The URL of the recorded audio file.

StartConferenceOnEnter
string

When a participant has this set on true and they join a call, conference begins.

StatusCallbackEvent
string

Conference state changes. Possible events are: conference-end, conference-start, participant-leave, participant-join, participant-mute, participant-unmute, participant-hold, participant-unhold, participant-speech-start, participant-speech-stop.

Timestamp
string

The timestamp, in RFC 2822 format, of when an event occurred.

Request parameters for the recordingStatusCallback URL

Payload
1{
2  "AccountSid": "b3877c40-da60-4998-90ad-b792e98472af",
3  "CallSid": "b3877c40-da60-4998-90ad-b792e98472ca",
4  "RecordingSid": "b3877c40-da60-4998-90ad-b792e984re01",
5  "RecordingUrl": "https://example.signalwire.com/api/laml/2010-04-01/Accounts/b3877c40-da60-4998-90ad-b792e98472af/Recordings/b3877c40-da60-4998-90ad-b792e984re01",
6  "RecordingStatus": "completed",
7  "RecordingDuration": 94,
8  "RecordingChannels": 1,
9  "RecordingSource": "RecordVerb"
10}

Status values for the recordingStatusCallbackEvent attribute

The recordingStatusCallbackEvent attribute has the following status values:

ValueDescription
in-progressThe recording has begun.
completedThe recording has completed and is accessible.
failedThe recording is not accessible because of a failure.

Examples

A simple conference call

1<?xml version="1.0" encoding="UTF-8"?>
2<Response>
3  <Dial>
4    <Conference>Room 1234</Conference>
5  </Dial>
6</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

1<?xml version="1.0" encoding="UTF-8"?>
2<Response>
3  <Dial>
4    <Conference startConferenceOnEnter="false">
5      moderated-conference-room
6    </Conference>
7  </Dial>
8</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

1<?xml version="1.0" encoding="UTF-8"?>
2<Response>
3  <Dial>
4    <Conference startConferenceOnEnter="true" endConferenceOnExit="true">
5      moderated-conference-room
6    </Conference>
7  </Dial>
8</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)

1<?xml version="1.0" encoding="UTF-8"?>
2<Response>
3  <Dial>
4    <Conference muted="true">ConferenceRoom</Conference>
5  </Dial>
6</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

1<?xml version="1.0" encoding="UTF-8"?>
2<Response>
3  <Dial>
4    <Conference coach="AgentCallSid">
5      Example-Room
6    </Conference>
7  </Dial>
8</Response>

Recording a conference call

1<?xml version="1.0" encoding="UTF-8"?>
2<Response>
3  <Dial>
4    <Conference record="record-from-start"
5                recordingStatusCallback="https://www.example.com/recording_update">
6      ConferenceCall
7    </Conference>
8  </Dial>
9</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.