Twilio

The Conference Noun

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.

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

By default, Twilio conference rooms enable a number of useful features used by business conference bridges:

• Conferences do 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.

Each of these features can be turned on or off, based on your needs.

Noun Attributes

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 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. This defaults to true.

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 ended and all other participants drop out. This defaults to false. This 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 can be replaced with your own music and messages. The TwiML that executes in the waitUrl is currently limited to <Play>, <Say>, and <Redirect>. <Record>, <Dial>, and <Gather> are not allowed. If you do not wish anything to play while waiting for the conference to start, specify the empty string (waitUrl="").

If no waitUrl is specified, Twilio will use it's 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

Which points at bucket com.twilio.music.classical, containing a selection of nice, Creative Commons classical music. Here's a list of S3 buckets we've assembed with other genres of music that you can also use:

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.

Examples

Example 1: A Simple Conference

<Response>
  <Dial>
    <Conference>1234</Conference>
  </Dial>
</Response>

By default, the first caller to execute this TwiML would join conference 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.

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">1234</Conference>
  </Dial>
</Response>

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

<Response>
  <Dial>
    <Conference startConferenceOnEnter="true" endConferenceOnExit="true" >1234</Conference>
  </Dial>
</Response>

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

Example 3: Join a Conference Muted

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

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

Example 4: Bridging Calls

<Response>
  <Dial>
    <Conference beep="false" waitUrl="" startConferenceOnJoin="true" endConferenceOnExit="true">
      NoMusicNoBeepRoom
    </Conference>
  </Dial>
</Response>

Sometimes you just want to bridge to 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.

Example 5: 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", then 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 "endConferenceOnExt" will cause the conference to end.

Example 6: Combining with Dial attributes

<Response>
  <Dial action="handleLeaveConference.php" method="POST" hangupOnStar="true" timeLimit="30">
    <Conference>LoveTwilio</Conference>
  </Dial>
</Response>

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.