---
title: "Join a conference"
method: POST
path: "/conferences/{id}/actions/join"
tags: ["Conference Commands"]
---

# 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:**

- `conference.participant.joined`
- `conference.participant.left`

## Path parameters

- `id` string, required

## Request body

- JoinConferenceRequest
  - `call_control_id` string, required — 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` '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` '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.
  - `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).

## Response `200`

Successful response upon making a conference command.

- object
  - `data` ConferenceCommandResult
    - `result` string, required

## Other responses

- `401` — Unauthorized. Authentication failed - the required authentication headers were either invalid or not included in the request.
- `422` — Unprocessable entity. The request was well-formed but could not be processed due to semantic errors. This includes validation errors, invalid parameter values, call state errors, conference errors, queue errors, recording/transcription errors, and business logic violations.

---

[API](https://skmtc.net/team-telnyx/apis/telnyx-api-2.md) · [All operations](https://skmtc.net/team-telnyx/apis/telnyx-api-2/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/team-telnyx/telnyx-api-2/versions/8f5f4e537994/schema)