You can use the Conference element to start a conference call, and callers can then join to talk to others connected to that call. Conference names are mapped to a user account, which means that two accounts with same conference name will dial into different conferences. The maximum number of members in a single conference is 20.

​
Attributes

muted
boolean

Indicates whether the conference is muted. To mute each member who joins a conference, set this attribute to true. The member will still be able to listen to the people in the conference.

Allowed values: true, false
Defaults to false.

enterSound
string

The sound to be played when a member enters the conference.

You can play a single beep by using beep:1 and a double beep with beep:2. If a URL is specified, the URL is fetched with an HTTP POST request; the application at the URL must return an XML document with Play, Speak, and/or Wait elements only. All other elements are ignored.

Allowed values: “”, beep:1, beep:2, or a valid URL
Defaults to “” (empty string).

exitSound
string

The sound to be played when a member exits the conference.

You can play a single beep by using beep:1 and a double beep with beep:2. If a URL is specified, the URL is fetched with an HTTP POST request; the application at the URL must return an XML document with Play, Speak, and/or Wait elements only. All other elements are ignored.

Allowed values: “”, beep:1, beep:2, or a valid URL
Defaults to “” (empty string).

startConferenceOnEnter
boolean

When a member joins a conference with this attribute set to true, the conference is started if not already in progress.

When a member joins a conference with this attribute set to false, and the conference has not yet started, the member is muted and hears background music until another member joins the conference. This attribute is handy when you’re organizing moderated conferences.

Allowed values: true, false
Defaults to true.

endConferenceOnExit
boolean

When a member with this attribute set to true leaves a conference, the conference ends and all other members are automatically removed from the conference. This attribute is handy when you’re organizing moderated conferences.

Allowed values: true, false
Defaults to false.

stayAlone
boolean

If a conference has this attribute set to false, the conference will end if a member is alone in it.

If a member joins the conference with the stayAlone attribute set to false, the conference will end if any member is alone in it. This attribute can change from true to false if a member joins the conference with this attribute set to false.

Once this attribute changed to false, it will not be updated to true if another member joins with the value for this attribute set to true.

Allowed values: true, false
Defaults to true.

waitSound
string
Callback-retry configurable

The URL of a sound file, fetched with HTTP POST request, to be played while the member is alone in the conference. The URL must return an XML document with Play, Speak and/or Wait elements only. All other elements are ignored.

Allowed values: absolute URL
Default behavior is that no music is played.

maxMembers
integer

Indicates the maximum number of members that are to be allowed within a named conference. This value can be any positive integer greater than 0.

When maxMembers is reached, the conference is skipped. If the next element in the XML response is the action_url, this is also skipped and the call proceeds to the next element after the Conference element.

Allowed values: integers between 1 and 20 (inclusive)
Defaults to 20.

Note: The default number of members per conference is 20 if maxMembers is not set when starting the conference. After being set by the first member, maxMembers cannot be changed by other members.
record
boolean

Indicates whether the conference should be recorded.

Allowed values: true, false
Defaults to false.

recordFileFormat
string

The file format for the recording.

Allowed values: mp3, wav
Defaults to mp3.

timeLimit
integer

Used to set the maximum duration of the conference in seconds.

For example, setting a time limit of 600 seconds will automatically end the conference after 10 minutes.

Allowed values: Any integer >= 0
Defaults to 86,400 seconds (24 hours).

hangupOnStar
boolean

If set to true, this attribute lets the member exit from the conference by pressing the * key on their phone, without having to hang up. If specified, action URL will be invoked upon the call’s exit from the Conference.

Allowed values: true, false
Defaults to false.

action
stringCallback-retry configurable

An absolute URL to which the API can send parameters. See the action request parameters table below for more information.

Allowed values: a fully qualified URL
No default value

method
string

Method used to send HTTP request to the action URL.

Allowed values: GET, POST
Defaults to POST.

callbackUrl
stringCallback-retry configurable

If specified, information is sent back to this URL. See the callbackUrl request parameters table below for more information.

Allowed values: a fully qualified URL
No default value.

callbackMethod
string

Method used to send HTTP request to the callbackUrl.

Allowed values: GET, POST
Defaults to POST.

transcriptionType
string

auto: Transcription is automated; the turnaround time is under 5 minutes which linearly increases with call duration.

Transcription charges and details are available on our pricing page.

Transcription service is available only in English, and limited to calls with a duration greater than 500 milliseconds and less than 4 hours, with a recording file size smaller than 2GB.

transcriptionUrl
string

The URL to which the transcription should be posted.

Allowed values: a fully qualified URL
No default value

The transcription information will be sent to this URL via an HTTP POST callback.

digitsMatch
string

A list of digits, which are sent to the callbackUrl when a user presses digits that match the digitsMatch parameter.

Allowed values: list of digits patterns separated by comma
No default value

floorEvent
boolean

If set to true, send notification to callbackUrl when member is the floor-holder.

Allowed values: true, false
Defaults to false.

redirect
boolean

If false, don’t redirect to action URL, only request the URL and continue to next element.

Allowed values: true, false
Defaults to true.

relayDTMF
boolean

Transmit all digits except digitsMatch to all members of conference.

Allowed values: true, false
Defaults to true.

​
Parameters sent to the action URL

ConferenceName

The conference name.

ConferenceUUID

Unique ID of the conference.

ConferenceMemberID

Member ID in the conference.

RecordUrl

URL of the recorded file. Only available if record is set to true.

RecordingID

ID of the recorded file. Only available if record is set to true.

​
Parameters sent to the callbackUrl

ConferenceAction
  • enter when user enters the conference
  • exit when user leaves the conference
  • digits when user presses matching digits
  • floor if user is the floor-holder in the conference
  • record if conference has been recorded using record attribute.
ConferenceName

The conference name.

ConferenceUUID

Unique ID of the conference.

ConferenceMemberID

ID of call in the conference.

Not present if ConferenceAction is set to record value.

CallUUID

Unique identifier for this call.

Not present if ConferenceAction is set to record value.

ConferenceDigitsMatch

The digits pattern matching when call has pressed digits.

Sent if ConferenceAction is set to digits value.

RecordUrl

The URL of the recorded file.

Sent if ConferenceAction is set to record value.

RecordingID

The ID of the recorded file.

Sent if ConferenceAction is set to record value.

RecordingDuration

Duration of recording in seconds.

Sent if ConferenceAction is set to record value. If recordSession or startOnDialAnswer is true, the duration is always -1.

RecordingDurationMs

Duration of recording in milliseconds.

Sent if ConferenceAction is set to record value.

RecordingStartMs

When the recording started (epoch time UTC) in milliseconds.

Sent if ConferenceAction is set to record value.

RecordingEndMs

When the recording ended (epoch time UTC) in milliseconds.

Sent if ConferenceAction is set to record value.

​
Parameters sent to the transcriptionUrl

transcription_charge

The credit deducted for the transcription.

transcription

The transcribed text of the recording.

duration

The duration in seconds of the recording.

call_uuid

The call UUID of the call which was transcribed.

transcription_rate

The rate of the transcription per minute.

recording_id

Recording ID of the recording that was transcribed.

errorMay be Recording duration too long for transcription or Recording file size too large for transcription. Empty if transcription is successful.
Note: .mp3 files are smaller in size than .wav files. Consider changing the recording file format to .mp3 if you see this error.

The next few sections show code for several conferencing tasks.