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.
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
- Beta Feature: receive a webhook when a participant speaks or stops speaking
You can configure or disable each of these features based on your particular needs.
The Conference noun supports the following attributes that modify its behavior:
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 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.
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:
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 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.
Whisper 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. Whisper is a feature of Agent Conference, which can be enabled via the Twilio Console .
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. and speaker. 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 .
* 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:
The unique identifier of the Account responsible for this recording.
A unique identifier for the conference associated with the recording.
The unique identifier for the recording.
The URL of the recorded audio.
The status of the recording. Possible values are: completed .
The length of the recording, in seconds
The number of channels in the final recording file as an integer. Only 1 channel is supported for Conference recordings.
The type of call that created this recording. Conference is returned for Conference recordings.
This attribute indicates which HTTP method to use when requesting ‘recordingStatusCallback’. It defaults to ‘POST’.
This parameter has been deprecated in favor of recordingStatusCallback. Providing a recordingStatusCallback will result in no eventCallback.
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.
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.
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.
Loading Code Samples.
Code Output Download Project View on GitHub Toggle Highlighted Lines Copy to Clipboard Link to this Code Full Screen Normal Size
Posted In: NEWS
conference, dial, in
Leave a Comment