TwiML™ Voice: <Conference>


The <Dial> verb's <Conference> noun allows you to connect to a conference room. Much like how the <Number> noun allows you to connect to another phone number, the <Conference> noun allows you to connect to a named conference room and talk with the other callers who have also connected to that room. Conference is commonly used as a container for calls when implementing hold, transfer, and barge.

Twilio offers a globally distributed, low latency conference system that hosts your conferences in the region closest to the majority of your participants and has a maximum participant capacity of 250. It has a per-participant-per-minute price in addition to standard voice minute pricing. Learn more about Conference pricing.


The name of the room is up to you and is namespaced to your account. This means that any caller who joins room1234 via your account will end up in the same conference room, but callers connecting through different accounts would not.

(warning)

Warning

For compliance reasons, do not use personal data (also known as personally identifiable information), such as phone numbers, email addresses, or a person's name, or any other sensitive information when naming the conferences

By default, Twilio conference rooms enable a number of useful features that can be enabled or disabled based on your particular needs:

  • Conferences will not start until at least two participants join.
  • While waiting, customizable background music is played.
  • When participants join and leave, notification sounds are played to inform the other participants.
  • Events can be configured to alert your application to state changes in a conference
  • Receive a webhook when a participant speaks or stops speaking

You can configure or disable each of these features based on your particular needs.


Noun Attributes

attributes page anchor

The <Conference> noun supports the following attributes that modify its behavior:

Attribute NameAllowed ValuesDefault Value
mutedtrue, falsefalse
beeptrue, false, onEnter, onExittrue
startConferenceOnEntertrue, falsetrue
endConferenceOnExittrue, falsefalse
participantLabela label for the conference participantNone
jitterBufferSizesmall, medium, large, offlarge
waitUrlTwiML URL, empty stringdefault Twilio hold music
waitMethodGET or POSTPOST
maxParticipantspositive integer <= 250250
recorddo-not-record or record-from-startdo-not-record
regionus1, ie1, de1, sg1, br1, au1, jp1None
trimtrim-silence or do-not-trimtrim-silence
coachA Call SIDnone
statusCallbackEventstart end join leave mute hold modify speaker announcementNone
statusCallbackrelative or absolute URLNone
statusCallbackMethodGET, POSTPOST
recordingStatusCallbackrelative or absolute URLNone
recordingStatusCallbackMethodGET, POSTPOST
recordingStatusCallbackEventin-progress, completed, absentcompleted
eventCallbackUrlrelative or absolute URLNone

The muted attribute lets you specify whether a participant can speak on the conference. If this attribute is set to true, the participant will only be able to listen to people on the conference. This attribute defaults to false.

To change a conference participant's muted attribute during a call use to the Conference Participant API.

The beep attribute lets you specify whether a notification beep is played to the conference when a participant joins or leaves the conference. Defaults to true.

ValueBehavior
trueDefault. Plays a beep both when a participant joins and when a participant leaves.
falseDisables beeps for when participants both join and exit.
onEnterOnly plays a beep when a participant joins. The beep will not be played when the participant exits.
onExitWill not play a beep when a participant joins; only plays a beep when the participant exits.

This attribute tells a conference to start when this participant joins the conference, if it is not already started. This is true by default. If this is false and the participant joins a conference that has not started, they are muted and hear background music until a participant joins where startConferenceOnEnter is true. This is useful for implementing moderated conferences.

If a participant has this attribute set to true, then when that participant leaves, the conference ends and all other participants drop out. This defaults to false. This is useful for implementing moderated conferences that bridge two calls and allow either call leg to continue executing TwiML if the other hangs up.

A unique label for the participant which will be added into the conference as a result of executing the TwiML. The label provided here can be used subsequently to read or update participant attributes using the Twilio REST API. The participantLabel must be unique across all participants in the conference, and there is a max limit of 128 characters.

(warning)

Warning

If a participant with the same label already exists in the conference, 16025 error notification will be reported, and visible on Twilio Console(link takes you to an external page). The call will not be added into the conference and instead continue to the next TwiML verb.

The jitterBufferSize attribute lets you set the jitter buffer behavior for a conference participant. Twilio Conference uses a jitter buffer to smooth out irregularity in media packet arrival times when mixing audio for conference participants. This buffer results in fewer audio artifacts, but introduces a fixed delay for the audio of each participant.

Setting the jitterBufferSize value to small will create a 20ms buffer that results in average latency of ~150ms - ~200ms on a stream with max jitter of ~20ms.

Setting the value to medium will create a 40ms buffer that results in average latency of ~200ms - ~360ms on a stream with max jitter of ~20ms.

The large setting, which is the default jitter buffer behavior, will create a 60ms buffer that results in average latency between ~300ms - ~1000ms on a stream with max jitter of ~20ms.

Spikes of extremely high jitter can result in the maximum latency exceeding the average latency by as much as 50%.

The off setting completely disables the buffer and packets with relatively low jitter ( <=20ms) will be completely dropped, but Twilio will add no extra latency when mixing.

The buffer value is a particpant-level setting, the value for participant A does not apply to participant B.

The waitUrl attribute lets you specify a URL for music that plays before the conference has started. The URL may return an MP3 file, a WAV file, or a TwiML document that contains <Play>, <Say>, <Pause>, or <Redirect> verbs. If the waitUrl responds with TwiML, <Record>, <Dial>, <Hangup>, and <Gather> verbs are not allowed. This defaults to a selection of Creative Commons licensed background music, but you can replace it with your own music and messages. If you do not wish anything to play while waiting for the conference to start, specify the empty string (set waitUrl to '').

If no waitUrl is specified, Twilio will use its own HoldMusic Twimlet(link takes you to an external page) that reads a public AWS S3 Bucket(link takes you to an external page) for audio files. The default waitUrl is: http://twimlets.com/holdmusic?Bucket=com.twilio.music.classical(link takes you to an external page)

If the request to your waitUrl fails, the Conference will not be fully established. To avoid the call being disconnected, you can either add additional TwiML after the initial <Dial> <Conference>, or programmatically provide fallback behavior via the action callback.

This URL points at S3 bucket com.twilio.music.classical(link takes you to an external page), containing a selection of nice Creative Commons classical music. Here's a list of S3 buckets we've assembled with other genres of music for you to choose from:

This attribute indicates which HTTP method to use when requesting waitUrl. It defaults to POST. Be sure to use GET if you are directly requesting static audio files such as WAV or MP3 files so that Twilio properly caches the files.

This attribute indicates the maximum number of participants you want to allow within a named conference room. The maximum number of participants is 250.

The record attribute lets you record an entire <Conference>. When set to record-from-start, the recording begins when the first two participants are bridged. The hold music is never recorded. If a recordingStatusCallback URL is given, Twilio will make a request to the specified URL with recording details when the recording is available to access.

The region attribute specifies the region where Twilio should mix the conference. Specifying a value for region overrides Twilio's automatic region selection logic and should only be used if you are confident you understand where your conferences should be mixed. Twilio sets the region parameter from the first participant that specifies the parameter and will ignore the parameter from subsequent participants.

The trim attribute lets you specify whether to trim leading and trailing silence from your audio files. trim defaults to trim-silence, which removes any silence at the beginning or end of your recording. This may cause the duration of the recording to be slightly less than the duration of the call.

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.

The statusCallbackEvent attribute allows you to specify which conference state changes should generate a Webhook to the URL specified in the statusCallback attribute. The available values are start, end, join, leave, mute, hold, modify, speaker, and announcement. To specify multiple values separate them with a space. Events are set by the first Participant to join the conference, subsequent statusCallbackEvents will be ignored. If you specify conference events you can see a log of the events fired for a given conference in the conference logs in the console(link takes you to an external page).

EventDescription
startThe conference has begun and audio is being mixed between all participants. This occurs when there are at least two participants in the conference, and at least one of the participants has startConferenceOnEnter="true".
endThe last participant has left the conference or a participant with endConferenceOnExit="true" leaves the conference.
joinA participant has joined the conference.
leaveA participant has left the conference.
muteA participant has been muted or unmuted.
holdA participant has been held or unheld.
modifyAt least one of a participant's attributes has been modified: BeepOnExit, EndConferenceOnExit, Coaching, WaitUrl
speakerA participant has started or stopped speaking.
announcementA participant or conference announcement has ended or failed. Currently, the announcement-fail event will only be sent if there is an internal Twilio error. We are working to add more failures to the announcement-fail event to allow developers to debug the issue.

The statusCallback attribute takes a URL as an argument. Conference events specified in the statusCallbackEvent parameter will be sent to this URL.

(warning)

Warning

The statusCallback URL is set by the first Participant to join the conference, subsequent setting of the statusCallback will be ignored.

The parameters contained in the events requests are detailed below.

The HTTP method Twilio should use when requesting the above URL. Defaults to POST

Twilio will pass the following parameters with its request to the statusCallback URL. For participant announcement events, Twilio will pass additional participant-related request parameters if the participant being announced to is still present in the conference.

ParameterExampleSent On
ConferenceSidCFe08c870b500f6e44a9ad184defd1f391Sent on: All
FriendlyNameMyConfSent on: All
AccountSidAC25e16e9a716a4a8617a7c83f58e30482Sent on: All
SequenceNumber1Sent on: All
TimestampThu, 1 Jun 2017 20:48:32 +0000Sent on: All
StatusCallbackEventconference-end conference-start participant-leave participant-join participant-mute participant-unmute participant-hold participant-unhold participant-modify participant-speech-start participant-speech-stop announcement-end announcement-failSent on: join leave start end mute hold modify speaker announcement
CallSidCA25e16e9a716a4a1786a7c83f58e30482Sent on: join leave mute hold modify speaker announcement (for participant announcements)
Mutedtrue, falseSent on: join leave mute hold modify speaker announcement (for participant announcements)
Holdtrue, falseSent on: join leave mute hold modify speaker announcement (for participant announcements)
Coachingtrue, falseSent on: join leave mute hold modify speaker announcement (for participant announcements)
EndConferenceOnExittrue, falseSent on: join leave mute hold modify speaker announcement (for participant announcements)
StartConferenceOnEntertrue, falseSent on: join leave mute hold modify speaker announcement (for participant announcements)
CallSidEndingConferenceCall SID of the participant who ended the conference (if applicable)Sent on: end
ParticipantLabelEndingConferenceLabel of the participant who ended the conference (if applicable)Sent on: end
ReasonConferenceEndedconference-ended-via-api last-participant-kicked last-participant-left participant-with-end-conference-on-exit-kicked participant-with-end-conference-on-exit-leftSent on: end
ReasonA message indicating why the conference endedSent on: end
ReasonAnnouncementFailedA message indicating why the announcement failedSent on: announcement
AnnounceUrlThe URL used for the announcementSent on: announcement
ParticipantCallStatusThe call status of the participant. Will be one of: no-answer busy in-progress failed canceled completedSent on: participant-leave
ReasonParticipantLeftThe reason the participant left the conference. Will be one of: conference_ended_via_api moderator_ended_conference participant_updated_via_api participant_hung_up participant_add_failedSent on: participant-leave
EventName *conference-record-endSent on: conference-record-end
RecordingUrl *https://api.twilio.com/2010-04-01/Accounts/AC123/Recordings/RE234(link takes you to an external page)Sent on: conference-record-end
Duration *6Sent on: conference-record-end
RecordingFileSize *90786Sent on: conference-record-end
(warning)

Warning

All conference-record-end parameters above have been deprecated in favor of recordingStatusCallback, which is the preferred approach to receive recording related information. Providing a recordingStatusCallback will result in no conference-record-end callbacks.

The recordingStatusCallback attribute takes a relative or absolute URL as an argument.

If a conference recording was requested via the record attribute and a recordingStatusCallback URL is given, Twilio will make a GET or POST request to the specified URL when the recording is available to access.

Twilio will pass the following parameters with its request to the recordingStatusCallback URL:

ParameterDescription
AccountSidThe unique identifier of the Account responsible for this recording.
ConferenceSidA unique identifier for the conference associated with the recording.
RecordingSidThe unique identifier for the recording.
RecordingUrlThe URL of the recorded audio.
RecordingStatusThe status of the recording. Possible values are: in-progress, completed,absent.
RecordingDurationThe length of the recording, in seconds
RecordingChannelsThe number of channels in the final recording file as an integer. Only 1 channel is supported for Conference recordings.
RecordingStartTimeThe timestamp of when the recording started.
RecordingSourceThe initiation method used to create this recording. Conference is returned for Conference recordings.

This attribute indicates which HTTP method to use when requesting recordingStatusCallback. It defaults to POST.

This attribute allows you to specify which recording status changes should generate a webhook to the URL specified in the recordingStatusCallback attribute. The available values are in-progress, completed, absent. To specify multiple values separate them with a space. Default is completed.

Details on the status change events below:

ParameterDescription
in-progressThe recording has started
completedThe recording is complete and available for access
absentThe recording is absent and not accessible
(information)

Info

To pause or resume conference recordings, see the Recording API Docs.

(warning)

Warning

This attribute is deprecated. Use recordingStatusCallback instead. When a recordingStatusCallback value is provided, Twilio does not send any HTTP requests to the eventCallbackUrl.

The 'eventCallbackUrl' attribute takes a URL as an argument. When the conference ends, Twilio will make a POST request to this URL with the conference-record-end event parameters of statusCallback.


Example 1: Conference

examples-1 page anchor

By default, the first caller to execute this TwiML would join the conference room named Room 1234 and listen to the default waiting music. When the next caller executed this TwiML, they would join the same conference room and the conference would start. The default background music ends, the notification beep is played and all parties can communicate.

1
const VoiceResponse = require('twilio').twiml.VoiceResponse;
2
3
4
const response = new VoiceResponse();
5
const dial = response.dial();
6
dial.conference('Room 1234');
7
8
console.log(response.toString());

Output

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

Example 2: A Moderated Conference

examples-2 page anchor

First, you can drop a number of people into the conference, specifying that the conference shouldn't yet start:

1
const VoiceResponse = require('twilio').twiml.VoiceResponse;
2
3
4
const response = new VoiceResponse();
5
const dial = response.dial();
6
dial.conference({
7
startConferenceOnEnter: false
8
}, 'moderated-conference-room');
9
10
console.log(response.toString());

Output

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>

Each person will hear hold music while they wait. When the "moderator" or conference organizer calls in, you can specify that the conference should begin:

1
const VoiceResponse = require('twilio').twiml.VoiceResponse;
2
3
4
const response = new VoiceResponse();
5
const dial = response.dial();
6
dial.conference({
7
startConferenceOnEnter: true,
8
endConferenceOnExit: true
9
}, 'moderated-conference-room');
10
11
console.log(response.toString());

Output

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>

Also note that since the moderator has "endConferenceOnExit='true'" set, then when the moderator hangs up, the conference will end and each participant's <Dial> will complete.

Example 3: Join an Evented Conference

examples-4 page anchor

This code will put you into a conference where events will be fired on the start, end, join, leave, mute, and hold state changes of the participant and conference.

1
const VoiceResponse = require('twilio').twiml.VoiceResponse;
2
3
4
const response = new VoiceResponse();
5
const dial = response.dial();
6
dial.conference({
7
statusCallback: 'https://myapp.com/events',
8
statusCallbackEvent: 'start end join leave mute hold'
9
}, 'EventedConf');
10
11
console.log(response.toString());

Output

1
<?xml version="1.0" encoding="UTF-8"?>
2
<Response>
3
<Dial>
4
<Conference statusCallback="https://myapp.com/events"
5
statusCallbackEvent="start end join leave mute hold">
6
EventedConf
7
</Conference>
8
</Dial>
9
</Response>

Example 4: Join a Conference Muted

examples-4-1 page anchor

This code allows participants to join the conference room muted. They can hear what unmuted participants are saying but no one can hear them. The muted attribute can be enabled or disabled in realtime via the REST API.

1
const VoiceResponse = require('twilio').twiml.VoiceResponse;
2
3
4
const response = new VoiceResponse();
5
const dial = response.dial();
6
dial.conference({
7
muted: true
8
}, 'SimpleRoom');
9
10
console.log(response.toString());

Output

1
<?xml version="1.0" encoding="UTF-8"?>
2
<Response>
3
<Dial>
4
<Conference muted="true">SimpleRoom</Conference>
5
</Dial>
6
</Response>

Example 5: Bridging Calls

examples-5 page anchor

Sometimes you just want to bridge two calls together without any of the bells and whistles. With this minimal conferencing attribute setup, no background music or beeps are played, participants can speak right away as they join, and the conference ends right away if either participant hangs up. This is useful for cases like bridging two existing calls, much like you would with a Dial.

1
const VoiceResponse = require('twilio').twiml.VoiceResponse;
2
3
4
const response = new VoiceResponse();
5
const dial = response.dial();
6
dial.conference({
7
beep: false,
8
waitUrl: 'http://your-webhook-host.com',
9
startConferenceOnEnter: true,
10
endConferenceOnExit: true
11
}, 'NoMusicNoBeepRoom');
12
13
console.log(response.toString());

Output

1
<?xml version="1.0" encoding="UTF-8"?>
2
<Response>
3
<Dial>
4
<Conference beep="false"
5
waitUrl="http://your-webhook-host.com"
6
startConferenceOnEnter="true"
7
endConferenceOnExit="true">
8
NoMusicNoBeepRoom
9
</Conference>
10
</Dial>
11
</Response>

Example 6: Call on Hold

examples-6 page anchor
1
const VoiceResponse = require('twilio').twiml.VoiceResponse;
2
3
4
const response = new VoiceResponse();
5
const dial = response.dial();
6
dial.conference({
7
beep: false
8
}, 'Customer Waiting Room');
9
10
console.log(response.toString());

Output

1
<?xml version="1.0" encoding="UTF-8"?>
2
<Response>
3
<Dial>
4
<Conference beep="false">
5
Customer Waiting Room
6
</Conference>
7
</Dial>
8
</Response>

This code puts the first caller into a waiting room, where they'll hear music. It's as if they're on hold, waiting for an agent or operator to help them.

Then, when the operator or agent is ready to talk to them... their call would execute:

1
const VoiceResponse = require('twilio').twiml.VoiceResponse;
2
3
4
const response = new VoiceResponse();
5
const dial = response.dial();
6
dial.conference({
7
beep: false,
8
endConferenceOnExit: true
9
}, 'Customer Waiting Room');
10
11
console.log(response.toString());

Output

1
<?xml version="1.0" encoding="UTF-8"?>
2
<Response>
3
<Dial>
4
<Conference beep="false" endConferenceOnExit="true">
5
Customer Waiting Room
6
</Conference>
7
</Dial>
8
</Response>

This code would join the operator with the person who was holding. Because the conference starts when they enter, the wonderful hold music the first person was hearing will stop, and the two people will begin talking. Because "beep='false'", the caller won't hear a ding when the agent answers, which is probably appropriate for this use case. When the operator hangs up, then 'endConferenceOnExit' will cause the conference to end.

Example 7: Combining with Dial attributes

examples-7 page anchor

Because Conference is an element of Dial, you can still use all the Dial attributes in combination with Conference (with the exception of callerId and timeout, which have no effect). You can set a timeLimit, after which you'll be removed from the conference. You can turn on hangupOnStar, which lets you leave a conference by pressing the * key. You can specify an action, so that after you leave the conference room Twilio will submit to the action and your web server can respond with new TwiML and continue your call.

1
const VoiceResponse = require('twilio').twiml.VoiceResponse;
2
3
4
const response = new VoiceResponse();
5
const dial = response.dial({
6
action: 'handleLeaveConference.php',
7
method: 'POST',
8
hangupOnStar: true,
9
timeLimit: 30
10
});
11
dial.conference('LoveTwilio');
12
13
console.log(response.toString());

Output

1
<?xml version="1.0" encoding="UTF-8"?>
2
<Response>
3
<Dial action="handleLeaveConference.php"
4
method="POST"
5
hangupOnStar="true"
6
timeLimit="30">
7
<Conference>LoveTwilio</Conference>
8
</Dial>
9
</Response>

Example 8: Recording a Conference

examples-8 page anchor

This code allows you to record an entire conference starting when the first two participants are bridged and will send a recordingStatusCallback when the conference recording is available for access.

1
const VoiceResponse = require('twilio').twiml.VoiceResponse;
2
3
4
const response = new VoiceResponse();
5
const dial = response.dial();
6
dial.conference({
7
record: 'record-from-start',
8
recordingStatusCallback: 'www.myexample.com'
9
}, 'LoveTwilio');
10
11
console.log(response.toString());

Output

1
<?xml version="1.0" encoding="UTF-8"?>
2
<Response>
3
<Dial>
4
<Conference record="record-from-start"
5
recordingStatusCallback="www.myexample.com">
6
LoveTwilio
7
</Conference>
8
</Dial>
9
</Response>