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

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

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

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

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

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

Coach accepts a call SID of a call that is currently connected to an 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

The 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

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.

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.

Possible Values: GET, POST

join_conference.recording_status_callback_event

string

The events to listen for and send to the recording status callback URL.

Possible Values: in-progress, completed, absent

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.

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

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

1 {
2   "event_type": "calling.conference",
3   "event_channel": "swml:xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
4   "timestamp": 1640000000.123,
5   "project_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
6   "space_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
7   "params": {
8     "call_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
9     "name": "my_conference",
10     "conference_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
11     "status": "participant-join",
12     "size": 3,
13     "muted": false,
14     "hold": false,
15     "start_on_join": true,
16     "end_on_leave": false,
17     "coaching": false
18   }
19 }

Conference end event example

1 {
2   "event_type": "calling.conference",
3   "event_channel": "swml:xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
4   "timestamp": 1640000000.456,
5   "project_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
6   "space_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
7   "params": {
8     "call_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
9     "name": "my_conference",
10     "conference_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
11     "status": "conference-end",
12     "size": 0,
13     "reason_ended": "last-participant-left",
14     "call_id_ending_conf": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
15     "recording_url": "https://your-space.signalwire.com/api/v1/recordings/rec-uuid/download",
16     "recording_duration": 300,
17     "recording_file_size": 4800000
18   }
19 }

Examples

Basic Conference Join

1 version: 1.0.0
2 sections:
3   main:
4     - join_conference:
5         name: "team_meeting"

Conference with Custom Settings

1 version: 1.0.0
2 sections:
3   main:
4     - join_conference:
5         name: "team_meeting"
6         muted: false
7         beep: "onEnter"
8         start_on_enter: true
9         max_participants: 10
10         record: "record-from-start"

Conference with Status Callbacks

1 version: 1.0.0
2 sections:
3   main:
4     - join_conference:
5         name: "support_call"
6         status_callback_event: "join"
7         status_callback: "https://example.com/conference-status"
8         status_callback_method: "POST"
9         recording_status_callback: "https://example.com/recording-status"
10         recording_status_callback_event: "completed"