join_conference

Join an ad-hoc audio conference with RELAY and CXML calls. This method allows you to connect the current call to a named conference where multiple participants can communicate simultaneously.

Name	Type	Default	Description
join_conferenceRequired	object	-	An object that accepts the join_conference parameters.

join_conference Parameters

Name	Type	Default	Description
nameRequired	string	-	Name of conference.
mutedOptional	boolean	false	Whether to join the conference in a muted state. If set to true, the participant will be muted upon joining.
beepOptional	string	true	Sets the behavior of the beep sound when joining or leaving the conference. Possible Values: true, false, onEnter, onExit
start_on_enterOptional	boolean	true	Starts the conference when the main participant joins. This means the start action will not wait on more participants to join before starting.
end_on_exitOptional	boolean	false	Ends the conference when the main participant leaves. This means the end action will not wait on more participants to leave before ending.
wait_urlOptional	string	-	A URL that will play media when the conference is put on hold. Default hold music will be played if not set.
max_participantsOptional	integer	250	The maximum number of participants allowed in the conference. If the limit is reached, new participants will not be able to join.
recordOptional	string	do-not-record	Enables or disables recording of the conference. Possible Values: do-not-record, record-from-start
regionOptional	string	-	Specifies the geographical region where the conference will be hosted.
trimOptional	string	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
coachOptional	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.
status_callback_eventOptional	string	-	The events to listen for and send to the status callback URL. Possible Values: start, end, join, leave, mute, hold, modify, speaker, announcement
status_callbackOptional	string	-	The URL to which status events will be sent. This URL must be publicly accessible and able to handle HTTP requests.
status_callback_methodOptional	string	POST	The HTTP method to use when sending status events to the status callback URL. Possible Values: GET, POST
recording_status_callbackOptional	string	-	The URL to which recording status events will be sent. This URL must be publicly accessible and able to handle HTTP requests.
recording_status_callback_methodOptional	string	POST	The HTTP method to use when sending recording status events to the recording status callback URL. Possible Values: GET, POST
recording_status_callback_eventOptional	string	-	The events to listen for and send to the recording status callback URL. Possible Values: in-progress, completed, absent
resultOptional	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

Variable	Direction	Description
join_conference_result	out	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	out	Contains the same value as join_conference_result for use in conditional logic.

Examples

Basic Conference Join

YAML

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

JSON

{
  "version": "1.0.0",
  "sections": {
    "main": [
      {
        "join_conference": {
          "name": "team_meeting"
        }
      }
    ]
  }
}

Conference with Custom Settings

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

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

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

{
  "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"
        }
      }
    ]
  }
}