Sign in

v52

OpenAPI 3.1.0raw.githubusercontent.com2026-07-311,1941,9384.1 MB
Conference Commands

Join a conference

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:

  • conference.participant.joined
  • conference.participant.left
post/conferences/{id}/actions/join

Path parameters

idstring required

Uniquely identifies the conference by id or name

Request body

beep_enabled'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.

call_control_idstring required

Unique identifier and token for controlling the call

client_statestring

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_idstring

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_exitboolean

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

holdboolean

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

hold_audio_urlstring

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_namestring

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

muteboolean

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

region'Australia' | 'Europe' | 'Middle East' | 'US'

Region where the conference data is located. Defaults to the region defined in user's data locality settings (Europe or US).

soft_end_conference_on_exitboolean

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

start_conference_on_enterboolean

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

supervisor_role'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_idsstring[]

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.

Example request

{
  "beep_enabled": "always",
  "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"
  ]
}

Response

Successful response upon making a conference command.

Example response

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