API reference

Conferences

A conference is a named room where everyone can hear each other. A caller joins with <Dial><Conference>room-name</Conference></Dial>, and every call that dials the same name lands in the same room. The room opens when the first caller arrives and closes when the last one leaves. Conferences live entirely in your markup: there is no conferences REST API, and no API to mute or remove someone once they are in.

Connect is live. The API is v0.x, so field names may change before v1.

Room attributes

These belong to the room, so Connect takes them from the first caller who joins. The same attributes on later callers are ignored. Put them on every caller if you cannot tell who will arrive first.

Attribute	Type	Description
maxParticipants	integer	Most people allowed in the room. Defaults to 250. A caller who arrives when it is full is not added (see Full rooms below).
record	enum	record-from-start records the whole room, mixed, from the moment it opens. Defaults to do-not-record.
trim	enum	trim-silence or do-not-trim for the room recording. Defaults to do-not-trim.
statusCallback	url	Where Connect sends conference events. No callbacks are sent without it.
statusCallbackEvent	string	Space-separated events to send: any of start, end, join, leave. Defaults to all four ("start end join leave").
statusCallbackMethod	POST \| GET	Defaults to POST (JSON body). GET sends the same fields as query parameters.
recordingStatusCallback	url	Where Connect sends recording status callbacks for the room recording.
recordingStatusCallbackEvent	string	Space-separated recording statuses to send. Defaults to completed.
recordingStatusCallbackMethod	POST \| GET	Defaults to POST.

Per-caller attributes

These apply to the caller whose markup sets them.

Attribute	Type	Description
(body)required	string	The room name. Everyone whose markup dials the same name joins the same room.
muted	boolean	Join able to hear but not speak. Defaults to false.
beep	enum	true (beep when this caller joins and leaves), false, onEnter or onExit. Defaults to true.
startConferenceOnEnter	boolean	Defaults to true: the room starts when this caller joins. Set it to false for a caller who should wait (hearing the waitUrl or music on hold) until someone with true arrives.
endConferenceOnExit	boolean	When true, everyone else is hung up when this caller leaves. Defaults to false.
waitUrl	url	For a caller waiting for the room to start: Connect fetches it once and loops the Say, Play and Wait verbs it returns. Without it, or if it fails, the caller hears music on hold.
waitMethod	POST \| GET	HTTP method for waitUrl. Defaults to POST.
participantLabel	string	Your own label for this caller, for example agent-204. Sent back as ParticipantLabel on join and leave events.

Pick room names that are unique to you, for example with a random ID in them, so two unrelated calls never share a room.

Example

An agent joins the room and asks for every event. Because endConferenceOnExit is true, the room closes when the agent hangs up. The JSON form takes the same options inside dial.conference, or just the room name as a string.

Your webhook reply

<Response>
  <Say>Joining the support bridge.</Say>
  <Dial action="https://your.app/voice/after-conference">
    <Conference statusCallback="https://your.app/voice/conference-events"
                statusCallbackEvent="start end join leave"
                participantLabel="agent-204"
                endConferenceOnExit="true">support-bridge-4821</Conference>
  </Dial>
</Response>

200 ok

Conference status callbacks

When the room has a statusCallback, Connect sends one request per event you asked for. Each request has a 5 second timeout, is sent once with no retries, and is not signed (see Securing your endpoint). The X-CPaaS-Event header is conference.plus the event name. Start and end events have no CallSid and no X-CPaaS-Call-Sid header.

Field	Type	Description
StatusCallbackEvent	enum	start (the room opened), end (the room closed), join or leave.
ConferenceSid	string	The room name you chose. Sent on every event.
CallSid	string	The call that joined or left. join and leave only.
ParticipantLabel	string \| null	The caller's participantLabel, or null if none was set. join and leave only.
Muted	boolean	Whether the caller joined muted. join only.

POST your endpoint (join)

{
  "StatusCallbackEvent": "join",
  "ConferenceSid": "support-bridge-4821",
  "CallSid": "CA7Q2M9X4K1B8N3T6R0W5Y2Z9C1V4H7JL5",
  "ParticipantLabel": "agent-204",
  "Muted": false
}

Full rooms and the Dial action

If a caller arrives when the room already has maxParticipants people, they are not added. When the <Dial> has an action, Connect POSTs {"DialCallStatus": "full", "DialCallDuration": 0, "ConferenceSid": "support-bridge-4821"} to it, so you can tell the caller and offer something else.

Every verb and attribute is in Call-control markup. To record the room, see Recordings. To hold callers until an agent is free, use Queues.