- API & Docs
<Conference> noun allows you to connect to a conference
room. Much like how the
<Number> noun allows you to connect to another phone
<Conference> noun allows you to connect to a named conference
room and talk with the other callers who have also connected to that room.
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. The maximum number of participants in a single Twilio conference room is 40.
By default, Twilio conference rooms enable a number of useful features used by business conference bridges:
You can configure or disable each of these features based on your particular needs.
<Conference> noun supports the following attributes that modify its behavior:
|Attribute Name||Allowed Values||Default Value|
|beep||true, false, onEnter, onExit||true|
|waitUrl||TwiML url, empty string||default Twilio hold music|
|waitMethod||GET or POST||POST|
|maxParticipants||positive integer <= 40||40|
|record||do-not-record or record-from-start||do-not-record|
|trim||trim-silence or do-not-trim||trim-silence|
|eventCallbackUrl||relative or absolute URL||None|
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
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||Default. Plays a beep both when a participant joins and when a participant leaves.|
|false||Disables beeps for when participants both join and exit.|
|onEnter||Only plays a beep when a participant joins. The beep will not be played when the participant exits.|
|onExit||Will 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
true. This is useful for implementing moderated
If a participant has this attribute set to
true, then when that participant
leaves, the conference ends and all other participants drop out. This
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.
The 'waitUrl' attribute lets you specify a URL for music that plays before the
conference has started. The URL may be an MP3, a WAV or a TwiML document that uses
<Say> for content. This defaults to a selection of Creative Commons
licensed background music, but you can replace it with your own music and
messages. If the 'waitUrl' responds with TwiML, Twilio will only process
<Gather> verbs are not allowed. If you do not wish
anything to play while waiting for the conference to start, specify the empty string
(set 'waitUrl' to '').
This URL points at S3 bucket com.twilio.music.classical, 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 default maximum number of participants is 40. The value must be a positive integer less than or equal to 40.
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. A RecordingUrl parameter will be
sent to the ‘eventCallbackUrl’ on the associated
<Conference> verb. You
must set a ‘eventCallbackUrl’ to receive the RecordingUrl.
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.
The 'eventCallbackUrl' attribute takes a URL as an argument. When the conference ends, Twilio will make a POST request to this URL including the parameters below.
Twilio will pass the following parameters with its request to the 'eventCallbackUrl' URL:
|RecordingUrl||The URL of the recorded audio. This parameter is only sent if a recording is used with the
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.
<Response> <Dial> <Conference>Room 1234</Conference> </Dial> </Response>
First, you can drop a number of people into the conference, specifying that the conference shouldn't yet start:
<Response> <Dial> <Conference startConferenceOnEnter="false">moderated-conference-room</Conference> </Dial> </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:
<Response> <Dial> <Conference startConferenceOnEnter="true" endConferenceOnExit="true"> moderated-conference-room </Conference> </Dial> </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.
This code allows forces 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.
<Response> <Dial> <Conference muted="true">SimpleRoom</Conference> </Dial> </Response>
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.
<Response> <Dial> <Conference beep="false" waitUrl="" startConferenceOnEnter="true" endConferenceOnExit="true"> NoMusicNoBeepRoom </Conference> </Dial> </Response>
<Response> <Dial> <Conference beep="false"> Customer Waiting Room </Conference> </Dial> </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:
<Response> <Dial> <Conference beep="false" endConferenceOnExit="true"> Customer Waiting Room </Conference> </Dial> </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.
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.
<Response> <Dial action="handleLeaveConference.php" method="POST" hangupOnStar="true" timeLimit="30"> <Conference>LoveTwilio</Conference> </Dial> </Response>
This code allows you to record an entire conference starting when the first two participants are bridged.
<Response> <Dial> <Conference record="record-from-start" eventCallbackUrl="saveConferenceRecording.php">LoveTwilio</Conference> </Dial> </Response>