This is the API V2 documentation. To switch out of beta revert back to our API V1.

Open SidemenuAPI Reference
API Reference
Close Sidemenu

Conference Commands

List conferencesGetConferences

get https://api.telnyx.com/v2/conferences

Lists conferences. Conferences are created on demand, and will expire after all participants have left the conference or after 4 hours regardless of the number of active participants. Conferences are listed in descending order by expires_at.

curl -X GET \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --globoff "https://api.telnyx.com/v2/conferences?filter[name]=global_meeting&page[size]=10"
Parameters
In query
filter[name]
string
optional

If present, conferences will be filtered to those with a matching `name` attribute. Matching is case-sensitive

page[number]
integer (1)
optional

The page number to load

Default: 1
page[size]
integer (1- 250)
optional

The size of the page

Default: 20
Responses
200

A paginated array of conferences

401

Unauthorized

422

Unprocessable entity

Success Response
{
  "data": [
    {
      "created_at": "2019-01-23T18:10:02.574Z",
      "end_reason": "all_left",
      "ended_by": {
        "call_control_id": "AgDIxmoRX6QMuaIj_uXRXnPAXP0QlNfXczRrZvZakpWxBlpw48KyZQ==",
        "call_session_id": "428c31b6-abf3-3bc1-b7f4-5013ef9657c1"
      },
      "expires_at": "2019-01-23T18:10:02.574Z",
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "All hands meeting",
      "record_type": "conference",
      "region": "sv1",
      "status": "completed",
      "updated_at": "2019-01-23T18:10:02.574Z"
    }
  ],
  "meta": {
    "page_number": 2,
    "page_size": 25,
    "total_pages": 3,
    "total_results": 55
  }
}

Create conferenceCreateConference

post https://api.telnyx.com/v2/conferences

Create a conference from an existing call leg using a call_control_id and a conference name. Upon creating the conference, the call will be automatically bridged to the conference. Conferences will expire after all participants have left the conference or after 4 hours regardless of the number of active participants.

Expected Webhooks:

  • conference.created
  • conference.participant.joined
  • conference.participant.left
  • conference.ended
  • conference.recording.saved
curl -X POST \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --data '{"name": "Business", "call_control_id": "891510ac-f3e4-11e8-af5b-de00688a4931"}' \
  https://api.telnyx.com/v2/conferences
Parameters
In body
call_control_id
string
required

Unique identifier and token for controlling the call

Example: "AgDIxmoRX6QMuaIj_uXRXnPAXP0QlNfXczRrZvZakpWxBlpw48KyZQ=="
name
string
required

Name of the conference

Example: "Business"
beep_enabled
string
optional

Whether a beep sound should be played when participants join and/or leave the conference.

Example: "on_exit"
Options: [ "always", "never", "on_enter", "on_exit" ]
client_state
string
optional

Use this field to add state to every subsequent webhook. It must be a valid Base-64 encoded string.

Example: "aGF2ZSBhIG5pY2UgZGF5ID1d"
command_id
string
optional

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.

Example: "891510ac-f3e4-11e8-af5b-de00688a4901"
duration_minutes
integer
optional

Time length (minutes) after which the conference will end.

Example: 5
hold_audio_url
string
optional

The URL to an audio file to be played to participants joining the conference. Takes effect only when "start_conference_on_create" is set to "false".

Example: "http://www.example.com/audio.wav"
start_conference_on_create
boolean
optional

Whether the conference should be started on creation. If the conference isn't started all participants that join are automatically put on hold. Defaults to "true".

Responses
200

Expected response to successful conference creation

401

Unauthorized

422

Unprocessable entity

Success Response
{
  "data": {
    "created_at": "2019-01-23T18:10:02.574Z",
    "end_reason": "all_left",
    "ended_by": {
      "call_control_id": "AgDIxmoRX6QMuaIj_uXRXnPAXP0QlNfXczRrZvZakpWxBlpw48KyZQ==",
      "call_session_id": "428c31b6-abf3-3bc1-b7f4-5013ef9657c1"
    },
    "expires_at": "2019-01-23T18:10:02.574Z",
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "All hands meeting",
    "record_type": "conference",
    "region": "sv1",
    "status": "completed",
    "updated_at": "2019-01-23T18:10:02.574Z"
  }
}
Expected Webhooks
conference Created
{
  "data": {
    "event_type": "conference.created",
    "id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
    "payload": {
      "call_control_id": "AgDIxmoRX6QMuaIj_uXRXnPAXP0QlNfX",
      "call_leg_id": "428c31b6-7af4-4bcb-b7f5-5013ef9657c1",
      "call_session_id": "428c31b6-abf3-3bc1-b7f4-5013ef9657c1",
      "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
      "conference_id": "428c31b6-abf3-3bc1-b7f4-5013ef9657c1",
      "connection_id": "7267xxxxxxxxxxxxxx",
      "occurred_at": "2018-02-02T22:25:27.521Z"
    },
    "record_type": "event"
  }
}
conference Ended
{
  "data": {
    "event_type": "conference.ended",
    "id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
    "payload": {
      "call_control_id": "AgDIxmoRX6QMuaIj_uXRXnPAXP0QlNfX",
      "call_leg_id": "428c31b6-7af4-4bcb-b7f5-5013ef9657c1",
      "call_session_id": "428c31b6-abf3-3bc1-b7f4-5013ef9657c1",
      "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
      "conference_id": "428c31b6-abf3-3bc1-b7f4-5013ef9657c1",
      "connection_id": "7267xxxxxxxxxxxxxx",
      "occurred_at": "2018-02-02T22:25:27.521Z",
      "reason": "all_left"
    },
    "record_type": "event"
  }
}
conference Participant Joined
{
  "data": {
    "event_type": "conference.participant.joined",
    "id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
    "occurred_at": "2018-02-02T22:25:27.521Z",
    "payload": {
      "call_control_id": "AgDIxmoRX6QMuaIj_uXRXnPAXP0QlNfX",
      "call_leg_id": "428c31b6-7af4-4bcb-b7f5-5013ef9657c1",
      "call_session_id": "428c31b6-abf3-3bc1-b7f4-5013ef9657c1",
      "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
      "conference_id": "428c31b6-abf3-3bc1-b7f4-5013ef9657c1",
      "connection_id": "7267xxxxxxxxxxxxxx"
    },
    "record_type": "event"
  }
}
conference Participant Left
{
  "data": {
    "event_type": "conference.participant.left",
    "id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
    "occurred_at": "2018-02-02T22:25:27.521Z",
    "payload": {
      "call_control_id": "AgDIxmoRX6QMuaIj_uXRXnPAXP0QlNfX",
      "call_leg_id": "428c31b6-7af4-4bcb-b7f5-5013ef9657c1",
      "call_session_id": "428c31b6-abf3-3bc1-b7f4-5013ef9657c1",
      "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
      "conference_id": "428c31b6-abf3-3bc1-b7f4-5013ef9657c1",
      "connection_id": "7267xxxxxxxxxxxxxx"
    },
    "record_type": "event"
  }
}

Retrieve a conferenceGetConference

get https://api.telnyx.com/v2/conferences/{id}

Retrieve an existing conference

curl -X GET \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --globoff "https://api.telnyx.com/v2/conferences/{id}"
Parameters
In path
id
string
required

Uniquely identifies the conference by id or name

Responses
200

A conference

404

Conference does not exist

Success Response
{
  "data": {
    "created_at": "2019-01-23T18:10:02.574Z",
    "end_reason": "all_left",
    "ended_by": {
      "call_control_id": "AgDIxmoRX6QMuaIj_uXRXnPAXP0QlNfXczRrZvZakpWxBlpw48KyZQ==",
      "call_session_id": "428c31b6-abf3-3bc1-b7f4-5013ef9657c1"
    },
    "expires_at": "2019-01-23T18:10:02.574Z",
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "All hands meeting",
    "record_type": "conference",
    "region": "sv1",
    "status": "completed",
    "updated_at": "2019-01-23T18:10:02.574Z"
  }
}

Join a conferenceJoinConference

post https://api.telnyx.com/v2/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.

Expected Webhooks:

  • conference.participant.joined
  • conference.participant.left
curl -X POST \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --data '{"call_control_id": "891510ac-f3e4-11e8-af5b-de00688a4931"}' \
  https://api.telnyx.com/v2/conferences/{id}/actions/join
Parameters
In path
id
string
required

Uniquely identifies the conference by id or name

In body
call_control_id
string
required

Unique identifier and token for controlling the call

Example: "AgDIxmoRX6QMuaIj_uXRXnPAXP0QlNfXczRrZvZakpWxBlpw48KyZQ=="
client_state
string
optional

Use this field to add state to every subsequent webhook. It must be a valid Base-64 encoded string.

Example: "aGF2ZSBhIG5pY2UgZGF5ID1d"
command_id
string
optional

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.

Example: "891510ac-f3e4-11e8-af5b-de00688a4901"
end_conference_on_exit
boolean
optional

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

Example: true
hold
boolean
optional

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

Example: true
hold_audio_url
string
optional

The URL of an audio file to be played to the participant when they are put on hold after joining the conference. This property takes effect only if "hold" is set to "true".

Example: "http://www.example.com/audio.wav"
mute
boolean
optional

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

Example: true
soft_end_conference_on_exit
boolean
optional

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

Example: true
start_conference_on_enter
boolean
optional

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

Example: true
supervisor_role
string
optional

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

Example: "whisper"
Options: [ "barge", "monitor", "none", "whisper" ]
whisper_call_control_ids
array of string
optional

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: [ "v2:Sg1xxxQ_U3ixxxyXT_VDNI3xxxazZdg6Vxxxs4-GNYxxxVaJPOhFMRQ", "v2:qqpb0mmvd-ovhhBr0BUQQn0fld5jIboaaX3-De0DkqXHzbf8d75xkw" ]
Responses
200

Conference command response

401

Unauthorized

422

Unprocessable entity

Success Response
{
  "data": {
    "result": "ok"
  }
}
Expected Webhooks
conference Participant Joined
{
  "data": {
    "event_type": "conference.participant.joined",
    "id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
    "occurred_at": "2018-02-02T22:25:27.521Z",
    "payload": {
      "call_control_id": "AgDIxmoRX6QMuaIj_uXRXnPAXP0QlNfX",
      "call_leg_id": "428c31b6-7af4-4bcb-b7f5-5013ef9657c1",
      "call_session_id": "428c31b6-abf3-3bc1-b7f4-5013ef9657c1",
      "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
      "conference_id": "428c31b6-abf3-3bc1-b7f4-5013ef9657c1",
      "connection_id": "7267xxxxxxxxxxxxxx"
    },
    "record_type": "event"
  }
}
conference Participant Left
{
  "data": {
    "event_type": "conference.participant.left",
    "id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
    "occurred_at": "2018-02-02T22:25:27.521Z",
    "payload": {
      "call_control_id": "AgDIxmoRX6QMuaIj_uXRXnPAXP0QlNfX",
      "call_leg_id": "428c31b6-7af4-4bcb-b7f5-5013ef9657c1",
      "call_session_id": "428c31b6-abf3-3bc1-b7f4-5013ef9657c1",
      "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
      "conference_id": "428c31b6-abf3-3bc1-b7f4-5013ef9657c1",
      "connection_id": "7267xxxxxxxxxxxxxx"
    },
    "record_type": "event"
  }
}

Mute conference participantsMuteConference

post https://api.telnyx.com/v2/conferences/{id}/actions/mute

Mute a list of participants in a conference call

curl -X POST \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --data '{"call_control_ids": ["891510ac-f3e4-11e8-af5b-de00688a4931"]}' \
  https://api.telnyx.com/v2/conferences/{id}/actions/mute
Parameters
In path
id
string
required

Uniquely identifies the conference by id or name

In body
call_control_ids
array of string
optional

Array of unique identifiers and tokens for controlling the call. When empty all participants will be muted.

Responses
200

Conference command response

401

Unauthorized

404

Conference does not exist

422

Unprocessable entity

Success Response
{
  "data": {
    "result": "ok"
  }
}

Unmute conference participantsUnmuteConference

post https://api.telnyx.com/v2/conferences/{id}/actions/unmute

Unmute a list of participants in a conference call

curl -X POST \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --data '{"call_control_ids": ["891510ac-f3e4-11e8-af5b-de00688a4931"]}' \
  https://api.telnyx.com/v2/conferences/{id}/actions/unmute
Parameters
In path
id
string
required

Uniquely identifies the conference by id or name

In body
call_control_ids
array of string
optional

List of unique identifiers and tokens for controlling the call. Enter each call control ID to be unmuted. When empty all participants will be unmuted.

Responses
200

Conference command response

401

Unauthorized

404

Conference does not exist

422

Unprocessable entity

Success Response
{
  "data": {
    "result": "ok"
  }
}

Hold conference participantsHoldConference

post https://api.telnyx.com/v2/conferences/{id}/actions/hold

Hold a list of participants in a conference call

curl -X POST \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --data '{"call_control_ids": ["891510ac-f3e4-11e8-af5b-de00688a4931"], "audio_url": "http://example.com/message.wav"}' \
  https://api.telnyx.com/v2/conferences/{id}/actions/hold
Parameters
In path
id
string
required

Uniquely identifies the conference by id or name

In body
audio_url
string
optional

The URL of a file to be played back at the beginning of each prompt. The URL can point to either a WAV or MP3 file.

Example: "http://example.com/message.wav"
call_control_ids
array of string
optional

List of unique identifiers and tokens for controlling the call. When empty all participants will be placed on hold.

Responses
200

Conference command response

401

Unauthorized

404

Conference does not exist

422

Unprocessable entity

Success Response
{
  "data": {
    "result": "ok"
  }
}

Unhold conference participantsUnholdConference

post https://api.telnyx.com/v2/conferences/{id}/actions/unhold

Unhold a list of participants in a conference call

curl -X POST \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --data '{"call_control_ids": ["891510ac-f3e4-11e8-af5b-de00688a4931"], "audio_url": "http://example.com/message.wav"}' \
  https://api.telnyx.com/v2/conferences/{id}/actions/unhold
Parameters
In path
id
string
required

Uniquely identifies the conference by id or name

In body
call_control_ids
array of string
required

List of unique identifiers and tokens for controlling the call. Enter each call control ID to be unheld.

Responses
200

Conference command response

401

Unauthorized

404

Conference does not exist

422

Unprocessable entity

Success Response
{
  "data": {
    "result": "ok"
  }
}

Was this section helpful?was-this-page-helpful