join_conference

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

objectRequired

An object that accepts the following properties.

join_conference.name

stringRequired

Name of conference.

join_conference.muted

booleanDefaults to false

Whether to join the conference in a muted state. If set to true, the participant will be muted upon joining.

join_conference.beep

stringDefaults to 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

booleanDefaults to true

Whether this participant can start the conference. A conference starts once at least one participant with start_on_enter set to true has joined and the number of participants has reached min_participants (2 by default). Until then, participants wait.

join_conference.end_on_exit

booleanDefaults to 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 that SignalWire requests with an HTTP GET while this participant waits for the conference to start. Default hold music is played if not set. Set it to an empty string ("") to play silence instead.

join_conference.max_participants

integerDefaults to 250

The maximum number of participants allowed in the conference, up to 250. If the limit is reached, new participants will not be able to join.

join_conference.min_participants

integerDefaults to 2

The number of participants that must join before the conference starts. Set it to 1 to let a single participant with start_on_enter start the conference. Use a value from 1 up to max_participants. When both are set, a min_participants larger than max_participants is rejected. An invalid number written directly in the document makes the document invalid, so it doesn’t run. An invalid value that comes from a variable, such as 0 or a number larger than max_participants, makes the join fail and sets join_conference_result to failed.

Like max_participants, it is set when the conference is created; joining an existing conference doesn’t change it.

join_conference.record

stringDefaults to do-not-record

Enables or disables recording of the conference. With record-from-start, recording starts once at least two participants have joined, even if min_participants lets the conference start earlier. Recording is configured when the conference is created.

Possible Values: do-not-record, record-from-start

join_conference.region

stringDefaults to global

Specifies the geographical region requested for hosting the conference.

Possible Values: global, us, eu, ch

join_conference.trim

stringDefaults to 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. 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. When status_callback is set and this list is not set or empty, only end is sent.

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.

join_conference.status_callback_method

stringDefaults to POST

The HTTP method to use when sending status events to the status callback URL. Notifications in the relay format (see status_callback_event_type) are always sent with POST, even if GET is set.

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.

join_conference.recording_status_callback_method

stringDefaults to POST

The HTTP method to use when sending recording status events to the recording status callback URL. Notifications in the relay format (see recording_status_callback_event_type) are always sent with POST, even if GET is set.

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.emit_call_quality

booleanDefaults to false

When true, a participant-call-quality event with audio quality statistics is sent when this participant leaves, if statistics are available. To receive it, include leave in status_callback_event. See status callbacks for the fields.

join_conference.stream

object

Attach a 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.

The stream is set up only while the conference has not started yet. A stream sent by a participant joining a conference that has already started does not add a stream.

join_conference.stream.url

stringRequired

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

stringDefaults to POST

The HTTP method to use when sending stream status events to the status URL.

Possible Values: GET, POST

join_conference.stream.realtime

booleanDefaults to false

Has no effect on conference streams. A boolean value is accepted, but conference streams currently ignore 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. Possible values: joined (the participant joined the conference) or failed (the participant could not join). The value is set when join_conference finishes, not at the moment the participant joins.

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.

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. For participant events, the channel of the participant’s call. For conference and recording events, the conference 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, participant-call-quality, announcement-end, announcement-fail, record-start, record-pause, record-resume, record-stop.

announcement-end and announcement-fail are sent when status_callback_event includes announcement. participant-call-quality is sent when a participant that joined with emit_call_quality: true leaves, if status_callback_event includes leave and audio statistics are available.

params.conference_node_id

string

The ID of the node hosting the conference. Differs from node_id, which on participant events is the node handling the participant’s call.

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.subscriber_id

string

The ID of the subscriber on the participant’s call. Present on participant events when known.

params.address_id

string

The ID of the Resource Address on the participant’s call. Present on participant events when known.

params.subscriber_name

string

The name of the subscriber on the participant’s call. Present on participant events when known.

params.video

boolean

true for a video conference. Absent for audio conferences.

params.preview_url

string

URL of a periodically refreshed preview image of a video conference. Present only when previews are enabled.

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.deaf

boolean

Whether the participant can’t hear the conference. Present on participant events.

params.video_muted

boolean

Whether the participant’s video is muted. Present on participant events in video conferences.

params.coaching

boolean

Whether the participant is in coaching mode. Present on participant events.

params.call_id_to_coach

string

The call ID of the participant being coached. Present on participant events when the participant is coaching.

params.announce_url

string

The announcement URL set for the participant. Present on participant events when one is set.

params.meta

object

Metadata attached to the participant’s call. Present on participant events when the call has metadata.

params.meta.public

object

Public metadata. Can hold any JSON values, passed through as set.

params.meta.private

object

Private metadata. Can hold any JSON values, passed through as set. It is included in these webhooks.

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.

Audio quality statistics on participant-call-quality events are sent as strings, and each one is included only when its value is available.

params.rtt_avg

string

Average round-trip time. Present on participant-call-quality events when available.

params.rtt_min

string

Minimum round-trip time. Present on participant-call-quality events when available.

params.rtt_max

string

Maximum round-trip time. Present on participant-call-quality events when available.

params.out_jitter_min

string

Minimum outbound jitter. Present on participant-call-quality events when available.

params.out_jitter_max

string

Maximum outbound jitter. Present on participant-call-quality events when available.

params.out_jitter_avg

string

Average outbound jitter. Present on participant-call-quality events when available.

params.out_lost

string

Outbound lost packets. Present on participant-call-quality events when available.

params.in_media_bytes

string

Inbound media bytes. Present on participant-call-quality events when available.

params.in_media_packet_count

string

Inbound media packets. Present on participant-call-quality events when available.

params.in_skip_packet_count

string

Inbound skipped packets. Present on participant-call-quality events when available.

params.in_jitter_packet_count

string

Inbound jitter packets. Present on participant-call-quality events when available.

params.in_dtmf_packet_count

string

Inbound DTMF packets. Present on participant-call-quality events when available.

params.in_cng_packet_count

string

Inbound comfort noise (CNG) packets. Present on participant-call-quality events when available.

params.in_flush_packet_count

string

Inbound flushed packets. Present on participant-call-quality events when available.

params.in_flaws_total

string

Total inbound media flaws. Present on participant-call-quality events when available.

params.in_quality_percentage

string

Inbound audio quality percentage. Present on participant-call-quality events when available.

params.in_mos

string

Inbound mean opinion score (MOS). Present on participant-call-quality events when available.

params.out_media_bytes

string

Outbound media bytes. Present on participant-call-quality events when available.

params.out_media_packet_count

string

Outbound media packets. Present on participant-call-quality events when available.

params.out_dtmf_packet_count

string

Outbound DTMF packets. Present on participant-call-quality events when available.

params.out_cng_packet_count

string

Outbound comfort noise (CNG) packets. Present on participant-call-quality events when available.

Participant join event example

{
  "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",
    "conference_node_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "status": "participant-join",
    "size": 3,
    "muted": false,
    "deaf": false,
    "hold": false,
    "start_on_join": true,
    "end_on_leave": false,
    "coaching": false
  }
}

Conference end event example

{
  "event_type": "calling.conference",
  "event_channel": "aaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
  "timestamp": 1640000000.456,
  "project_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "space_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "params": {
    "name": "my_conference",
    "conference_id": "aaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
    "conference_node_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

version: 1.0.0
sections:
  main:
    - join_conference:
        name: "team_meeting"

Conference with Custom Settings

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

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

version: 1.0.0
sections:
  main:
    - join_conference:
        name: "team_meeting"
        stream:
          url: "wss://example.com/conference-audio"
          codec: "PCMU"
          status_url: "https://example.com/stream-status"