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 Conference is designed for high availability with Global and Basic Conference options. You can configure your account with the Global Conference or Basic Conference option in your Account Portal.

Global Conference

Global Conference 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.

Basic Conference

Basic Conference hosts your conferences in the US and has a maximum participant capacity of 40. Pricing is included in the standard per-minute voice pricing.

Customizable Features

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.

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.

Beta Feature: Events can be configured to notify your application of state changes for the conference and each participant.

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

Noun Attributes

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

Attribute Name Allowed Values Default Value
muted true, false false
beep true, false, onEnter, onExit true
startConferenceOnEnter true, false true
endConferenceOnExit true, false false
waitUrl TwiML URL, empty string default Twilio hold music
waitMethod GET or POST POST
maxParticipants Global Conference
positive integer <= 250

Basic Conference
positive integer <= 40
Global Conference: 250


Basic Conference: 40
record do-not-record or record-from-start do-not-record
trim trim-silence or do-not-trim trim-silence
statusCallbackEvent start end join leave mute hold None
statusCallback relative or absolute URL None
statusCallbackMethod GET, POST POST
eventCallbackUrl relative or absolute URL None

muted

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.

beep

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.

Value Behavior
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.

startConferenceOnEnter

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.

endConferenceOnExit

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.

waitUrl

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 <Play> or <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 <Play>, <Say>, and <Redirect> verbs. <Record>, <Dial>, and <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 '').

If no 'waitUrl' is specified, Twilio will use its own HoldMusic Twimlet that reads a public AWS S3 Bucket for audio files. The default 'waitUrl' is:

http://twimlets.com/holdmusic?Bucket=com.twilio.music.classical

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:

Bucket Twimlet URL
com.twilio.music.classical http://twimlets.com/holdmusic?Bucket=com.twilio.music.classical
com.twilio.music.ambient http://twimlets.com/holdmusic?Bucket=com.twilio.music.ambient
com.twilio.music.electronica http://twimlets.com/holdmusic?Bucket=com.twilio.music.electronica
com.twilio.music.guitars http://twimlets.com/holdmusic?Bucket=com.twilio.music.guitars
com.twilio.music.rock http://twimlets.com/holdmusic?Bucket=com.twilio.music.rock
com.twilio.music.soft-rock http://twimlets.com/holdmusic?Bucket=com.twilio.music.soft-rock

waitMethod

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.

maxParticipants

This attribute indicates the maximum number of participants you want to allow within a named conference room. The maximum number of participants is 40 for Basic Conference and 250 for Global Conference.

record

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 'statusCallback' on the associated <Conference> verb. You must set a 'statusCallback' to receive the RecordingUrl.

trim

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.

statusCallbackEvent

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, and hold. To specify multiple values separate them with a space. The events are fired on the following state changes.

Event Description
start The conference has begun and audio is being mixed between all participants. This occurs when there is at least one participant in the conference and a participant with startConferenceOnEnter="true" joins.
end The last participant has left the conference or a participant with endConferenceOnExit="true" leaves the conference.
join A participant has joined the conference.
leave A participant has left the conference.
mute A participant has been muted or unmuted.
hold A participant has been held or unheld.

statusCallback

The 'statusCallback' attribute takes a URL as an argument. Conference events specified in the 'statusCallbackEvent' parameter will be sent to this URL. The parameters contained in the events requests are detailed below.

statusCallbackMethod

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

eventCallbackUrl

This parameter has been deprecated in favor of 'statusCallback' and does not support conference events. If you specify a statusCallback it will override 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 including the parameters below.

Request Parameters

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

Parameter Example Sent On
ConferenceSid CFe08c870b500f6e44a9ad184defd1f391 Sent on: All
FriendlyName AgentConf Sent on: All
AccountSid AC25e16e9a716a4a8617a7c83f58e30482 Sent on: All
EventName conference-record-end Sent on: conference-record-end
StatusCallbackEvent conference-record-end
conference-end
conference-start
participant-leave
participant-join
participant-mute
participant-unmute
participant-hold
participant-unhold
Sent on: All
CallSid CA25e16e9a716a4a1786a7c83f58e30482 Sent on: join leave start end mute hold
Muted true, false Sent on: join leave start end mute hold
Hold true, false Sent on: join leave start end mute hold
EndConferenceOnExit true, false Sent on: join leave mute hold
StartConferenceOnEnter true, false Sent on: join leave mute hold
RecordingUrl https://api.twilio.com/2010-04-01/Accounts/AC123/Recordings/RE234 Sent on: conference-record-end
Duration 6 Sent on: conference-record-end
timestamp 1449014020 Sent on: conference-record-end
RecordingFileSize 90786 Sent on: conference-record-end

Examples

Example 1: A Simple Conference

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>

Example 2: A Moderated Conference

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.

Example 3: Join an Evented Conference

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.

<Response>
  <Dial>
    <Conference statusCallback="https://myapp.com/events" statusCallbackEvent="start end join leave mute hold">
      EventedConf
    </Conference>
  </Dial>
</Response>

Example 4: Join a Conference Muted

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.

<Response>
  <Dial>
    <Conference muted="true">SimpleRoom</Conference>
  </Dial>
</Response>

Example 5: Bridging Calls

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>

Example 6: Call on Hold

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

Example 7: Combining with Dial attributes

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>

Example 8: Recording a Conference

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>