> Fetch clean Markdown by appending `.md` to any page URL under https://signalwire.com/docs or requesting it with the HTTP header `Accept: text/markdown`. The root index at https://signalwire.com/docs/llms.txt lists the available documentation indexes. # join_conference > Join an ad-hoc audio conference with Relay and CXML calls. [statuscallbacks]: #statuscallbacks Join an ad-hoc audio conference started on either the SignalWire or Compatibility API. This method allows you to connect the current call to a named conference where multiple participants can communicate simultaneously. ## **Properties** **`join_conference`** `object` — required An object that accepts the following properties. --- **`join_conference.name`** `string` — required Name of conference. --- **`join_conference.muted`** `boolean` — default: false Whether to join the conference in a muted state. If set to `true`, the participant will be muted upon joining. --- **`join_conference.beep`** `string` — default: true Sets the behavior of the beep sound when joining or leaving the conference. **Possible Values**: `true`, `false`, `onEnter`, `onExit` --- **`join_conference.start_on_enter`** `boolean` — default: true Starts the conference when the main participant joins. This means the start action will not wait on more participants to join before starting. --- **`join_conference.end_on_exit`** `boolean` — default: false Ends the conference when the main participant leaves. This means the end action will not wait on more participants to leave before ending. --- **`join_conference.wait_url`** `string` A URL to fetch SWML while waiting for the conference to start (before a `start_on_enter` participant joins). SignalWire sends a POST request with the standard [document-fetching webhook](/docs/swml#document-fetching-webhook) body. The response should be a SWML document containing audio to play (e.g., hold music). Default hold music will be played if not set. --- **`join_conference.max_participants`** `integer` — default: 100000 The maximum number of participants allowed in the conference. If the limit is reached, new participants will not be able to join. --- **`join_conference.record`** `string` — default: do-not-record Enables or disables recording of the conference. **Possible Values**: `do-not-record`, `record-from-start` --- **`join_conference.region`** `string` Specifies the geographical region where the conference will be hosted. **Possible Values**: `global`, `us`, `eu`, `ch` --- **`join_conference.trim`** `string` — default: trim-silence If set to `trim-silence`, it will remove silence from the start of the recording. If set to `do-not-trim`, it will keep the silence. **Possible Values**: `trim-silence`, `do-not-trim` --- **`join_conference.coach`** `string` Joins the conference in coaching mode for the participant identified by the given [call SID](/docs/platform/what-is-a-sid). The coach hears the whole conference, but is heard only by the coached participant -- the other participants cannot hear the coach. Use this to whisper guidance to an agent while they are on a live call. The call SID must belong to a call that is currently connected to the in-progress conference. Specifying a call SID that does not exist or is no longer connected will result in a failure. --- **`join_conference.status_callback_event`** `string` A space-separated list of one or more events to listen for and send to the status callback URL. **Possible Values**: `start`, `end`, `join`, `leave`, `mute`, `hold`, `modify`, `speaker`, `announcement` --- **`join_conference.status_callback_event_type`** `string` The content type used when sending status events to the status callback URL. **Possible Values**: `cxml`, `laml`, `relay` --- **`join_conference.status_callback`** `string` The URL to which status events will be sent. This URL must be publicly accessible and able to handle HTTP requests. Learn more about [status callbacks][statuscallbacks]. --- **`join_conference.status_callback_method`** `string` — default: POST The HTTP method to use when sending status events to the status callback URL. **Possible Values**: `GET`, `POST` --- **`join_conference.recording_status_callback`** `string` The URL to which recording status events will be sent. This URL must be publicly accessible and able to handle HTTP requests. Learn more about [status callbacks][statuscallbacks]. --- **`join_conference.recording_status_callback_method`** `string` — default: POST The HTTP method to use when sending recording status events to the recording status callback URL. **Possible Values**: `GET`, `POST` --- **`join_conference.recording_status_callback_event`** `string` A space-separated list of one or more events to listen for and send to the recording status callback URL. **Possible Values**: `in-progress`, `completed`, `absent` --- **`join_conference.recording_status_callback_event_type`** `string` The content type used when sending recording status events to the recording status callback URL. **Possible Values**: `cxml`, `laml`, `relay` --- **`join_conference.result`** `object` Allows the user to specify a custom action to be executed when the conference result is returned (typically when it has ended). The actions can a `switch` object or a `cond` array. The `switch` object allows for conditional execution based on the result of the conference, while the `cond` array allows for multiple conditions to be checked in sequence. If neither is provided, the default action will be to end the conference. --- **`join_conference.stream`** `object` Attach a bidirectional WebSocket stream to the conference. Conference audio is streamed to the `url`, enabling real-time audio processing, transcription, or AI agents that listen to the conference. Uses the same stream schema as the `stream` device type in [`connect`](/docs/swml/reference/calling/connect). --- **`join_conference.stream.url`** `string` — required Secure WebSocket URL (must start with `wss://`) that the conference audio is streamed to. Plain `ws://` is not supported. --- **`join_conference.stream.name`** `string` A friendly name to identify the stream at the WebSocket endpoint. --- **`join_conference.stream.codec`** `string` Audio codec for the streamed audio. Supported values: `PCMU`, `PCMA`, `G722`, `L16`. Codec can include rate and ptime modifiers (e.g., `PCMU@40i`, `L16@24000h@40i`). --- **`join_conference.stream.status_url`** `string` HTTP or HTTPS URL to which stream status events will be sent. --- **`join_conference.stream.status_url_method`** `string` — default: POST The HTTP method to use when sending stream status events to the status URL. **Possible Values**: `GET`, `POST` --- **`join_conference.stream.realtime`** `boolean` — default: false When `true`, enables bidirectional audio so your endpoint can stream audio back into the conference (not just receive it). --- **`join_conference.stream.authorization_bearer_token`** `string` Bearer token sent in the `Authorization` header when the WebSocket connection is opened, so your endpoint can authenticate the request. --- **`join_conference.stream.custom_parameters`** `object` Custom key-value pairs delivered to your WebSocket endpoint when the stream connects. Use them to pass context such as a session or customer ID. --- ## **Variables** **`join_conference_result`** `string` The result of the conference join attempt. Possible values: `completed` (successfully joined and left the conference), `answered` (successfully joined the conference), `no-answer` (failed to join due to no answer), `failed` (failed to join due to an error), `canceled` (join attempt was canceled). --- **`return_value`** `string` Contains the same value as `join_conference_result` for use in conditional logic. --- ## **StatusCallbacks** > **Status callbacks are advisory** > > Status callbacks are asynchronous, best-effort HTTP notifications: delivery can be delayed or fail silently — if your server is unreachable, the callback simply never arrives. Don't gate time-critical or business-critical actions solely on receiving one. Confirm state via the REST API before acting, or use a transport with visible failure modes — see [Status callback reliability](/docs/platform/webhooks#status-callback-reliability). A POST request will be sent to `status_callback` with a JSON payload for events specified in `status_callback_event`. Both conference and recording events share the same `calling.conference` event type; the specific event is identified by `params.status`. **`event_type`** `string` The type of event. Always `calling.conference`. --- **`event_channel`** `string` The channel for the event, includes the SWML session ID. --- **`timestamp`** `number` Unix timestamp (float) when the event was generated. --- **`project_id`** `string` The project ID associated with the call. --- **`space_id`** `string` The Space ID associated with the call. --- **`params`** `object` An object containing conference-specific parameters. --- **`params.call_id`** `string` The call ID of the participant. --- **`params.name`** `string` The name of the conference. --- **`params.conference_id`** `string` The unique ID of the conference. --- **`params.status`** `string` The conference event. **Valid values:** `conference-start`, `conference-end`, `participant-join`, `participant-leave`, `participant-mute`, `participant-unmute`, `participant-hold`, `participant-unhold`, `participant-speech-start`, `participant-speech-stop`, `participant-modify`, `record-start`, `record-pause`, `record-resume`, `record-stop`. --- **`params.size`** `number` The number of participants currently in the conference. --- **`params.node_id`** `string` The node identifier. --- **`params.segment_id`** `string` The segment ID for the call. Present when available. --- **`params.region`** `string` The geographical region of the conference. --- **`params.tag`** `string` The tag associated with the call. Present when set. --- **`params.muted`** `boolean` Whether the participant is muted. Present on participant events. --- **`params.hold`** `boolean` Whether the participant is on hold. Present on participant events. --- **`params.start_on_join`** `boolean` Whether the participant starts the conference on join. --- **`params.end_on_leave`** `boolean` Whether the participant ends the conference on leave. --- **`params.coaching`** `boolean` Whether the participant is in coaching mode. Present on participant events. --- **`params.recording_url`** `string` URL to the conference recording. Present on `conference-end` and `record-stop` events when a recording exists. --- **`params.recording_file_size`** `number` Recording file size in bytes. Present on `conference-end` and `record-stop` events. --- **`params.recording_duration`** `number` Recording duration in seconds. Present on `conference-end` and `record-stop` events. --- **`params.reason_ended`** `string` The reason the conference ended. Present on `conference-end` events. --- **`params.call_id_ending_conf`** `string` The call ID of the participant that ended the conference. Present on `conference-end` events. --- #### Participant join event example ```json { "event_type": "calling.conference", "event_channel": "swml:xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "timestamp": 1640000000.123, "project_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "space_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "params": { "call_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "name": "my_conference", "conference_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "status": "participant-join", "size": 3, "muted": false, "hold": false, "start_on_join": true, "end_on_leave": false, "coaching": false } } ``` #### Conference end event example ```json { "event_type": "calling.conference", "event_channel": "swml:xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "timestamp": 1640000000.456, "project_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "space_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "params": { "call_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "name": "my_conference", "conference_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "status": "conference-end", "size": 0, "reason_ended": "last-participant-left", "call_id_ending_conf": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "recording_url": "https://your-space.signalwire.com/api/v1/recordings/rec-uuid/download", "recording_duration": 300, "recording_file_size": 4800000 } } ``` --- ## **Examples** ### Basic Conference Join #### YAML ```yaml version: 1.0.0 sections: main: - join_conference: name: "team_meeting" ``` #### JSON ```json { "version": "1.0.0", "sections": { "main": [ { "join_conference": { "name": "team_meeting" } } ] } } ``` ### Conference with Custom Settings #### YAML ```yaml version: 1.0.0 sections: main: - join_conference: name: "team_meeting" muted: false beep: "onEnter" start_on_enter: true max_participants: 10 record: "record-from-start" ``` #### JSON ```json { "version": "1.0.0", "sections": { "main": [ { "join_conference": { "name": "team_meeting", "muted": false, "beep": "onEnter", "start_on_enter": true, "max_participants": 10, "record": "record-from-start" } } ] } } ``` ### Conference with Status Callbacks #### YAML ```yaml version: 1.0.0 sections: main: - join_conference: name: "support_call" status_callback_event: "join" status_callback: "https://example.com/conference-status" status_callback_method: "POST" recording_status_callback: "https://example.com/recording-status" recording_status_callback_event: "completed" ``` #### JSON ```json { "version": "1.0.0", "sections": { "main": [ { "join_conference": { "name": "support_call", "status_callback_event": "join", "status_callback": "https://example.com/conference-status", "status_callback_method": "POST", "recording_status_callback": "https://example.com/recording-status", "recording_status_callback_event": "completed" } } ] } } ``` ### Conference with a stream attached #### YAML ```yaml version: 1.0.0 sections: main: - join_conference: name: "team_meeting" stream: url: "wss://example.com/conference-audio" codec: "PCMU" realtime: true status_url: "https://example.com/stream-status" ``` #### JSON ```json { "version": "1.0.0", "sections": { "main": [ { "join_conference": { "name": "team_meeting", "stream": { "url": "wss://example.com/conference-audio", "codec": "PCMU", "realtime": true, "status_url": "https://example.com/stream-status" } } } ] } } ``` > Join an ad-hoc audio conference with Relay and CXML calls.