Skip to main content

Conference

Used to join the current call into a conference.

Conference names are created and specified by your application. Conferences are implicitly created the first time your application uses a conference name, and they are implicitly deleted when the last member leaves the conference. We will create a unique ID for the conference, so your conference names can be whatever you want. If the conference ends and then you later use the same conference name, a new unique ID will be created.

To programmatically end a conference and immediately remove all members, use the update conference endpoint. If a conference is ended this way, removed members will continue executing their current BXML document, starting with the verb right after the <Conference>, if any.

To programmatically remove a call from a conference while leaving other conference members in the conference, use the update call endpoint.

info

A maximum of 20 calls may be in a particular conference.

A conference may last for at most 24 hours.

BXML returned by responding to Bandwidth's webhooks will be queued and executed in the conference in the order they are received (without overlapping). If an error happens when executing a verb, it will continue to the next verb normally.

Only the following verbs are valid for conferences:

BXML containing unsupported verbs will be rejected completely.

Text Content#

NameDescription
nameThe name of the conference. Can contain up to 100 characters of letters, numbers, and the symbols -, _, and .

Attributes#

AttributeDescription
mute(optional) A boolean value to indicate whether the member should be on mute in the conference. When muted, a member can hear others speak, but others cannot hear them speak. Defaults to false.
hold(optional) A boolean value to indicate whether the member should be on hold in the conference. When on hold, a member cannot hear others, and they cannot be heard. Defaults to false.
callIdsToCoach(optional) A comma-separated list of call ids to coach. When a call joins a conference with this attribute set, it will coach the listed calls. Those calls will be able to hear and be heard by the coach, but other calls in the conference will not hear the coach.

Calls may be added to the conference in any order - if the matching calls are not already in the conference, then once the matching calls are added, the coach will be able to hear and speak to the matching calls. Note that this will not add the matching calls to the conference; each call must individually execute a <Conference> verb to join.

The coach can leave and rejoin the conference, but the conference may only have one coach at a time.
conferenceEventUrl(optional) URL to send Conference events to. The URL, method, username, and password are set by the BXML document that creates the conference, and all events related to that conference will be delivered to that same endpoint. If more calls join afterwards and also have this property (or any other webhook related properties like username and password), they will be ignored and the original webhook information will be used. This URL may be a relative endpoint.
conferenceEventMethod(optional) The HTTP method to use for the request to conferenceEventUrl. GET or POST. Default value is POST.
conferenceEventFallbackUrl(optional) A fallback url which, if provided, will be used to retry the conference webhook deliveries in case conferenceEventUrl fails to respond.
conferenceEventFallbackMethod(optional) The HTTP method to use to deliver the conference webhooks to conferenceEventFallbackUrl. GET or POST. Default value is POST.
username(optional) The username to send in the HTTP request to conferenceEventUrl.
password(optional) The password to send in the HTTP request to conferenceEventUrl.
fallbackUsername(optional) The username to send in the HTTP request to conferenceEventFallbackUrl.
fallbackPassword(optional) The password to send in the HTTP request to conferenceEventFallbackUrl.
tag(optional) A custom string that will be sent with these and all future webhooks unless overwritten by a future tag attribute or <Tag> verb, or cleared.

May be cleared by setting tag=""

Max length 256 characters.

The tag that is set for the call that creates the conference is the tag that will be sent with all webhooks related to the conference. For example, if the call that creates the conference has a tag set, and another call with a different tag joins the same conference, the first call's tag will be sent with both conferenceMemberJoin events.
calbackTimeout(optional) This is the timeout (in seconds) to use when delivering webhooks for the conference. If not set, it will inherit the webhook timeout from the call that creates the conference. Can be any numeric value (including decimals) between 1 and 25.

Webhooks Received#

WebhooksCan reply with BXML
Conference CreatedYes
Conference Member JoinYes
Conference Member ExitYes
Conference CompletedNo

Examples#

Join a Conference#

<?xml version="1.0" encoding="UTF-8"?>
<Response>
<SpeakSentence gender="male">You will be added to your conference now.</SpeakSentence>
<Conference>my-conference-name</Conference>
</Response>

Join a Conference as a Coach#

This shows how to add a coach in a conference.

<?xml version="1.0" encoding="UTF-8"?>
<Response>
<SpeakSentence gender="male">Welcome. You are going to coach 2 calls, please wait.</SpeakSentence>
<Conference callIdsToCoach="c-95ac8d6e-1a31c52e-b38f-4198-93c1-51633ec68f8d,c-2a913f94-6a486f3a-3cae-4034-bcc3-f0c9fa77ca2f">my-conference-name</Conference>
</Response>