Join a conference

POST 
/conferences/:id/actions/join

Join an existing call leg to a conference. Issue the Join Conference command with the conference ID in the path and the call_control_id of the leg you wish to join to the conference as an attribute. The conference can have up to a certain amount of active participants, as set by the max_participants parameter in conference creation request.

Expected Webhooks (see callback schema below):

• conference.participant.joined
• conference.participant.left

Path Parameters

id stringrequired

Uniquely identifies the conference by id or name

application/json

Body

required

Join Conference request object

call_control_id stringrequired

Unique identifier and token for controlling the call

client_state string

Use this field to add state to every subsequent webhook. It must be a valid Base-64 encoded string. Please note that the client_state will be updated for the participient call leg and the change will not affect conferencing webhooks unless the participient is the owner of the conference.

command_id string

Use this field to avoid execution of duplicate commands. Telnyx will ignore subsequent commands with the same command_id as one that has already been executed.

end_conference_on_exit boolean

Whether the conference should end and all remaining participants be hung up after the participant leaves the conference. Defaults to "false".

soft_end_conference_on_exit boolean

Whether the conference should end after the participant leaves the conference. NOTE this doesn't hang up the other participants. Defaults to "false".

hold boolean

Whether the participant should be put on hold immediately after joining the conference. Defaults to "false".

hold_audio_url string

The URL of a file to be played to the participant when they are put on hold after joining the conference. hold_media_name and hold_audio_url cannot be used together in one request. Takes effect only when "start_conference_on_create" is set to "false". This property takes effect only if "hold" is set to "true".

hold_media_name string

The media_name of a file to be played to the participant when they are put on hold after joining the conference. The media_name must point to a file previously uploaded to api.telnyx.com/v2/media by the same user/organization. The file must either be a WAV or MP3 file. Takes effect only when "start_conference_on_create" is set to "false". This property takes effect only if "hold" is set to "true".

mute boolean

Whether the participant should be muted immediately after joining the conference. Defaults to "false".

start_conference_on_enter boolean

Whether the conference should be started after the participant joins the conference. Defaults to "false".

supervisor_role string

Possible values: [barge, monitor, none, whisper]

Sets the joining participant as a supervisor for the conference. A conference can have multiple supervisors. "barge" means the supervisor enters the conference as a normal participant. This is the same as "none". "monitor" means the supervisor is muted but can hear all participants. "whisper" means that only the specified "whisper_call_control_ids" can hear the supervisor. Defaults to "none".

whisper_call_control_ids string[]

Array of unique call_control_ids the joining supervisor can whisper to. If none provided, the supervisor will join the conference as a monitoring participant only.

beep_enabled string

Possible values: [always, never, on_enter, on_exit]

Whether a beep sound should be played when the participant joins and/or leaves the conference. Can be used to override the conference-level setting.

200: Successful response upon making a conference command.

application/json

• Schema
• Example (from schema)

Schema

data

object

result stringrequired

{
  "data": {
    "result": "ok"
  }
}

401: Unauthorized

422: Unprocessable entity

Request samples

• cURL

---

curl -L 'https://api.telnyx.com/v2/conferences/:id/actions/join' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <TOKEN>' \
-d '{
  "call_control_id": "v3:MdI91X4lWFEs7IgbBEOT9M4AigoY08M0WWZFISt1Yw2axZ_IiE4pqg",
  "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
  "command_id": "891510ac-f3e4-11e8-af5b-de00688a4901",
  "end_conference_on_exit": true,
  "hold": true,
  "hold_audio_url": "http://www.example.com/audio.wav",
  "mute": true,
  "start_conference_on_enter": true,
  "supervisor_role": "whisper",
  "whisper_call_control_ids": [
    "v2:Sg1xxxQ_U3ixxxyXT_VDNI3xxxazZdg6Vxxxs4-GNYxxxVaJPOhFMRQ",
    "v2:qqpb0mmvd-ovhhBr0BUQQn0fld5jIboaaX3-De0DkqXHzbf8d75xkw"
  ],
  "beep_enabled": "always"
}'

Response samples

• 200

---

{
  "data": {
    "result": "ok"
  }
}