Open SidemenuAPI Reference
API Reference
Close Sidemenu

Conference Commands

List conferenceslistConferences

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]=&page[number]=1"
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

Successful response with a list of conferences.

401

Unauthorized response. Happens when the current user is not a manager account.

422

Unprocessable entity

Success Response
{
  "data": [
    {
      "connection_id": "3fa85f64-9191-4567-b3fc-2c963f66afa6",
      "created_at": "2019-01-23T18:10:02.574Z",
      "end_reason": "all_left",
      "ended_by": {
        "call_control_id": "v2:T02llQxIyaRkhfRKxgAP8nY511EhFLizdvdUKJiSw8d6A9BborherQczRrZvZakpWxBlpw48KyZQ==",
        "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
  • conference.floor.changed
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 (application/json)
call_control_id
string
required

Unique identifier and token for controlling the call

Example: "v2:T02llQxIyaRkhfRKxgAP8nY511EhFLizdvdUKJiSw8d6A9BborherQczRrZvZakpWxBlpw48KyZQ=="
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.

Default: "never"
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"
comfort_noise
boolean
optional

Toggle background comfort noise.

Default: true
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 of a file to be played to participants joining the conference. The URL can point to either a WAV or MP3 file. 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".

Example: "http://example.com/message.wav"
hold_media_name
string
optional

The media_name of a file to be played to participants 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".

Example: "my_media_uploaded_to_media_storage_api"
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

Successful response with details about a conference.

401

Unauthorized response. Happens when the current user is not a manager account.

422

Unprocessable entity

Success Response
{
  "data": {
    "connection_id": "3fa85f64-9191-4567-b3fc-2c963f66afa6",
    "created_at": "2019-01-23T18:10:02.574Z",
    "end_reason": "all_left",
    "ended_by": {
      "call_control_id": "v2:T02llQxIyaRkhfRKxgAP8nY511EhFLizdvdUKJiSw8d6A9BborherQczRrZvZakpWxBlpw48KyZQ==",
      "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": "v2:T02llQxIyaRkhfRKxgAP8nY511EhFLizdvdUKJiSw8d6A9BborherQ",
      "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": "v2:T02llQxIyaRkhfRKxgAP8nY511EhFLizdvdUKJiSw8d6A9BborherQ",
      "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 Floor Changed
{
  "event_type": "conference.floor.changed",
  "id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
  "payload": {
    "call_control_id": "v2:T02llQxIyaRkhfRKxgAP8nY511EhFLizdvdUKJiSw8d6A9BborherQ",
    "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 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": "v2:T02llQxIyaRkhfRKxgAP8nY511EhFLizdvdUKJiSw8d6A9BborherQ",
      "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": "v2:T02llQxIyaRkhfRKxgAP8nY511EhFLizdvdUKJiSw8d6A9BborherQ",
      "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 conferenceretrieveConference

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

Responses
200

Successful response with details about a conference.

404

Conference does not exist

Success Response
{
  "data": {
    "connection_id": "3fa85f64-9191-4567-b3fc-2c963f66afa6",
    "created_at": "2019-01-23T18:10:02.574Z",
    "end_reason": "all_left",
    "ended_by": {
      "call_control_id": "v2:T02llQxIyaRkhfRKxgAP8nY511EhFLizdvdUKJiSw8d6A9BborherQczRrZvZakpWxBlpw48KyZQ==",
      "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 conferenceconferenceJoin

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 (application/json)
call_control_id
string
required

Unique identifier and token for controlling the call

Example: "v2:T02llQxIyaRkhfRKxgAP8nY511EhFLizdvdUKJiSw8d6A9BborherQczRrZvZakpWxBlpw48KyZQ=="
beep_enabled
string
optional

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.

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

Example: "http://example.com/message.wav"
hold_media_name
string
optional

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

Example: "my_media_uploaded_to_media_storage_api"
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

Successful response upon making a conference command.

401

Unauthorized response. Happens when the current user is not a manager account.

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": "v2:T02llQxIyaRkhfRKxgAP8nY511EhFLizdvdUKJiSw8d6A9BborherQ",
      "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": "v2:T02llQxIyaRkhfRKxgAP8nY511EhFLizdvdUKJiSw8d6A9BborherQ",
      "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 participantsconferenceMuteParticipants

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 (application/json)
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

Successful response upon making a conference command.

401

Unauthorized response. Happens when the current user is not a manager account.

404

Conference does not exist

422

Unprocessable entity

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

Unmute conference participantsconferenceUnmuteParticipants

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 (application/json)
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

Successful response upon making a conference command.

401

Unauthorized response. Happens when the current user is not a manager account.

404

Conference does not exist

422

Unprocessable entity

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

Hold conference participantsconferenceHoldParticipants

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 (application/json)
audio_url
string
optional

The URL of a file to be played to the participants when they are put on hold. media_name and audio_url cannot be used together in one request.

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.

media_name
string
optional

The media_name of a file to be played to the participants when they are put on hold. 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.

Example: "my_media_uploaded_to_media_storage_api"
Responses
200

Successful response upon making a conference command.

401

Unauthorized response. Happens when the current user is not a manager account.

404

Conference does not exist

422

Unprocessable entity

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

Unhold conference participantsconferenceUnholdParticipants

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"]}' \
  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 (application/json)
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

Successful response upon making a conference command.

401

Unauthorized response. Happens when the current user is not a manager account.

404

Conference does not exist

422

Unprocessable entity

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

Speak text to conference participantsconferenceSpeakText

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

Convert text to speech and play it to all or some participants.

curl -X POST \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --data '{"language":"en-US","payload":"Say this to participants"}' \
  https://api.telnyx.com/v2/conferences/{id}/actions/speak
Parameters
In path
id
string
required

Specifies the conference by id or name

In body (application/json)
language
string
required

The language used to speak the text.

Example: "en-US"
Options: [ "arb", "cmn-CN", "cy-GB", "da-DK", "de-DE", "en-AU", "en-GB", "en-GB-WLS", "en-IN", "en-US", "es-ES", "es-MX", "es-US", "fr-CA", "fr-FR", "hi-IN", "is-IS", "it-IT", "ja-JP", "ko-KR", "nb-NO", "nl-NL", "pl-PL", "pt-BR", "pt-PT", "ro-RO", "ru-RU", "sv-SE", "tr-TR" ]
payload
string
required

The text or SSML to be converted into speech. There is a 5,000 character limit.

Example: "Say this to participants"
voice
string
required

The gender of the voice used to speak the text.

Example: "female"
Options: [ "male", "female" ]
call_control_ids
array of string
optional

Call Control IDs of participants who will hear the spoken text. When empty all participants will hear the spoken text.

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"
payload_type
string
optional

The type of the provided payload. The payload can either be plain text, or Speech Synthesis Markup Language (SSML).

Default: "text"
Example: "ssml"
Options: [ "text", "ssml" ]
Responses
200

Successful response upon making a conference command.

401

Unauthorized response. Happens when the current user is not a manager account.

404

Conference does not exist

422

Unprocessable entity

Success Response
{
  "data": {
    "result": "ok"
  }
}
Expected Webhooks
conference Participant Speak Ended
{
  "data": {
    "event_type": "conference.participant.speak.ended",
    "id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
    "payload": {
      "call_control_id": "v2:T02llQxIyaRkhfRKxgAP8nY511EhFLizdvdUKJiSw8d6A9BborherQ",
      "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",
      "creator_call_session_id": "428c31b6-abf3-3bc1-b7f4-5013ef9657c1",
      "occurred_at": "2018-02-02T22:25:27.521Z"
    },
    "record_type": "event"
  }
}
conference Participant Speak Started
{
  "data": {
    "event_type": "conference.participant.speak.started",
    "id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
    "payload": {
      "call_control_id": "v2:T02llQxIyaRkhfRKxgAP8nY511EhFLizdvdUKJiSw8d6A9BborherQ",
      "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",
      "creator_call_session_id": "428c31b6-abf3-3bc1-b7f4-5013ef9657c1",
      "occurred_at": "2018-02-02T22:25:27.521Z"
    },
    "record_type": "event"
  }
}
conference Speak Ended
{
  "data": {
    "event_type": "conference.speak.ended",
    "id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
    "payload": {
      "conference_id": "428c31b6-abf3-3bc1-b7f4-5013ef9657c1",
      "connection_id": "7267xxxxxxxxxxxxxx",
      "creator_call_session_id": "428c31b6-abf3-3bc1-b7f4-5013ef9657c1",
      "occurred_at": "2018-02-02T22:25:27.521Z"
    },
    "record_type": "event"
  }
}
conference Speak Started
{
  "data": {
    "event_type": "conference.speak.started",
    "id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
    "payload": {
      "conference_id": "428c31b6-abf3-3bc1-b7f4-5013ef9657c1",
      "connection_id": "7267xxxxxxxxxxxxxx",
      "creator_call_session_id": "428c31b6-abf3-3bc1-b7f4-5013ef9657c1",
      "occurred_at": "2018-02-02T22:25:27.521Z"
    },
    "record_type": "event"
  }
}

Play audio to conference participantsconferencePlayAudio

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

Play audio to all or some participants on a conference call.

curl -X POST \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --data '{"audio_url":"http://www.example.com/sounds/greeting.wav"}' \
  https://api.telnyx.com/v2/conferences/{id}/actions/play
Parameters
In path
id
string
required

Uniquely identifies the conference by id or name

In body (application/json)
audio_url
string
optional

The URL of a file to be played back in the conference. media_name and audio_url cannot be used together in one request.

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

List of call control ids identifying participants the audio file should be played to. If not given, the audio file will be played to the entire conference.

loop
one of
optional

The number of times the audio file should be played. If supplied, the value must be an integer between 1 and 100, or the special string `infinity` for an endless loop.

Default: 1
Example: "infinity"
string
integer
media_name
string
optional

The media_name of a file to be played back in 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.

Example: "my_media_uploaded_to_media_storage_api"
Responses
200

Successful response upon making a conference command.

401

Unauthorized response. Happens when the current user is not a manager account.

404

Conference does not exist

422

Unprocessable entity

Success Response
{
  "data": {
    "result": "ok"
  }
}
Expected Webhooks
conference Participant Playback Ended
{
  "data": {
    "event_type": "conference.participant.playback.ended",
    "id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
    "payload": {
      "call_control_id": "v2:T02llQxIyaRkhfRKxgAP8nY511EhFLizdvdUKJiSw8d6A9BborherQ",
      "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",
      "creator_call_session_id": "428c31b6-abf3-3bc1-b7f4-5013ef9657c1",
      "media_name": "my_media_uploaded_to_media_storage_api",
      "media_url": "http://example.com/audio.wav",
      "occurred_at": "2018-02-02T22:25:27.521Z"
    },
    "record_type": "event"
  }
}
conference Participant Playback Started
{
  "data": {
    "event_type": "conference.participant.playback.started",
    "id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
    "payload": {
      "call_control_id": "v2:T02llQxIyaRkhfRKxgAP8nY511EhFLizdvdUKJiSw8d6A9BborherQ",
      "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",
      "creator_call_session_id": "428c31b6-abf3-3bc1-b7f4-5013ef9657c1",
      "media_name": "my_media_uploaded_to_media_storage_api",
      "media_url": "http://example.com/audio.wav",
      "occurred_at": "2018-02-02T22:25:27.521Z"
    },
    "record_type": "event"
  }
}
conference Playback Ended
{
  "data": {
    "event_type": "conference.playback.ended",
    "id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
    "payload": {
      "conference_id": "428c31b6-abf3-3bc1-b7f4-5013ef9657c1",
      "connection_id": "7267xxxxxxxxxxxxxx",
      "creator_call_session_id": "428c31b6-abf3-3bc1-b7f4-5013ef9657c1",
      "media_name": "my_media_uploaded_to_media_storage_api",
      "media_url": "http://example.com/audio.wav",
      "occurred_at": "2018-02-02T22:25:27.521Z"
    },
    "record_type": "event"
  }
}
conference Playback Started
{
  "data": {
    "event_type": "conference.playback.started",
    "id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
    "payload": {
      "conference_id": "428c31b6-abf3-3bc1-b7f4-5013ef9657c1",
      "connection_id": "7267xxxxxxxxxxxxxx",
      "creator_call_session_id": "428c31b6-abf3-3bc1-b7f4-5013ef9657c1",
      "media_name": "my_media_uploaded_to_media_storage_api",
      "media_url": "http://example.com/audio.wav",
      "occurred_at": "2018-02-02T22:25:27.521Z"
    },
    "record_type": "event"
  }
}

Stop audio being played on the conferenceconferenceStopAudio

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

Stop audio being played to all or some participants on 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":"array"}' \
  https://api.telnyx.com/v2/conferences/{id}/actions/stop
Parameters
In path
id
string
required

Uniquely identifies the conference by id or name

In body (application/json)
call_control_ids
array of string
optional

List of call control ids identifying participants the audio file should stop be played to. If not given, the audio will be stoped to the entire conference.

Responses
200

Successful response upon making a conference command.

401

Unauthorized response. Happens when the current user is not a manager account.

404

Conference does not exist

422

Unprocessable entity

Success Response
{
  "data": {
    "result": "ok"
  }
}
Expected Webhooks
conference Participant Playback Ended
{
  "data": {
    "event_type": "conference.participant.playback.ended",
    "id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
    "payload": {
      "call_control_id": "v2:T02llQxIyaRkhfRKxgAP8nY511EhFLizdvdUKJiSw8d6A9BborherQ",
      "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",
      "creator_call_session_id": "428c31b6-abf3-3bc1-b7f4-5013ef9657c1",
      "media_name": "my_media_uploaded_to_media_storage_api",
      "media_url": "http://example.com/audio.wav",
      "occurred_at": "2018-02-02T22:25:27.521Z"
    },
    "record_type": "event"
  }
}

Conference recording startconferenceStartRecording

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

Start recording the conference. Recording will stop on conference end, or via the Stop Recording command.

Expected Webhooks:

  • conference.recording.saved
curl -X POST \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --data '{"channels":"single","format":"wav"}' \
  https://api.telnyx.com/v2/conferences/{id}/actions/record_start
Parameters
In path
id
string
required

Specifies the conference to record by id or name

In body (application/json)
channels
string
required

When `dual`, final audio file will be stereo recorded with the first leg on channel A, and the rest on channel B.

Example: "single"
Options: [ "single", "dual" ]
format
string
required

The audio file format used when storing the call recording. Can be either `mp3` or `wav`.

Example: "mp3"
Options: [ "wav", "mp3" ]
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 duplicate commands. Telnyx will ignore commands with the same `command_id`.

Example: "891510ac-f3e4-11e8-af5b-de00688a4901"
max_length
integer (int32)
optional

Defines the maximum length for the recording in seconds. Minimum value is 0. Maximum value is 14400. Default is 0 (infinite)

Default: 0
Example: 100
play_beep
boolean
optional

If enabled, a beep sound will be played at the start of a recording.

Example: true
Responses
200

Successful response upon making a conference command.

401

Unauthorized response. Happens when the current user is not a manager account.

404

Conference does not exist

422

Unprocessable entity

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

Conference recording stopconferenceStopRecording

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

Stop recording the conference.

Expected Webhooks:

  • conference.recording.saved
curl -X POST \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --data '{"client_state":"aGF2ZSBhIG5pY2UgZGF5ID1d","command_id":"891510ac-f3e4-11e8-af5b-de00688a4901"}' \
  https://api.telnyx.com/v2/conferences/{id}/actions/record_stop
Parameters
In path
id
string
required

Specifies the conference to stop the recording for by id or name

In body (application/json)
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 duplicate commands. Telnyx will ignore commands with the same `command_id`.

Example: "891510ac-f3e4-11e8-af5b-de00688a4901"
Responses
200

Successful response upon making a conference command.

401

Unauthorized response. Happens when the current user is not a manager account.

404

Conference does not exist

422

Unprocessable entity

Success Response
{
  "data": {
    "result": "ok"
  }
}
Expected Webhooks
conference Recording Saved
{
  "data": {
    "event_type": "conference.recording.saved",
    "id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
    "payload": {
      "call_control_id": "v2:T02llQxIyaRkhfRKxgAP8nY511EhFLizdvdUKJiSw8d6A9BborherQ",
      "channels": "single",
      "conference_id": "428c31b6-abf3-3bc1-b7f4-5013ef9657c1",
      "connection_id": "7267xxxxxxxxxxxxxx",
      "format": "mp3",
      "public_recording_urls": {
        "mp3": "http://example.com/recording.mp3",
        "wav": "http://example.com/recording.wav"
      },
      "recording_ended_at": "2018-02-02T22:25:27.521992Z",
      "recording_id": "4577f9a2-cf0e-44f3-ac57-9f95fb03fa47",
      "recording_started_at": "2018-02-02T22:20:27.521992Z",
      "recording_urls": {
        "mp3": "http://example.com/recording.mp3",
        "wav": "http://example.com/recording.wav"
      }
    },
    "record_type": "event"
  }
}

List conference participantslistConferenceParticipants

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

Lists conference participants

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/{conference_id}/participants?filter[muted]=&filter[on_hold]="
Parameters
In path
conference_id
string
required

Uniquely identifies the conference by id

In query
filter[muted]
boolean
optional

If present, participants will be filtered to those who are/are not muted

filter[on_hold]
boolean
optional

If present, participants will be filtered to those who are/are not put on hold

filter[whispering]
boolean
optional

If present, participants will be filtered to those who are whispering or are not

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

Successful response with a list of conference participants.

401

Unauthorized response. Happens when the current user is not a manager account.

404

Conference does not exist

422

Unprocessable entity

Success Response
{
  "data": [
    {
      "call_control_id": "v2:v2:T02llQxIyaRkhfRKxgAP8nY511EhFLizdvdUKJiSw8d6A9BborherQczRrZvZakpWxBlpw48KyZQ",
      "call_leg_id": "3a15df2d-c801-4729-adf5-b56dd42e2abb",
      "conference": {
        "id": "41b9acd4-f4da-4ff5-a85c-e07e90b53f46",
        "name": "1"
      },
      "created_at": "2019-01-23T18:10:02.574Z",
      "end_conference_on_exit": true,
      "id": "dfadada7-af74-47bc-83a4-554275f55f5c",
      "muted": false,
      "on_hold": true,
      "record_type": "participant",
      "soft_end_conference_on_exit": true,
      "status": "joining",
      "updated_at": "2019-01-23T18:10:02.574Z",
      "whisper_call_control_ids": [
        "v2:Sg1xxxQ_U3ixxxyXT_VDNI3xxxazZdg6Vxxxs4-GNYxxxVaJPOhFMRQ",
        "v2:qqpb0mmvd-ovhhBr0BUQQn0fld5jIboaaX3-De0DkqXHzbf8d75xkw"
      ]
    }
  ],
  "meta": {
    "page_number": 2,
    "page_size": 25,
    "total_pages": 3,
    "total_results": 55
  }
}

Update conference participantconferenceUpdate

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

Update conference participant supervisor_role

curl -X POST \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --data '{"call_control_id":"v2:T02llQxIyaRkhfRKxgAP8nY511EhFLizdvdUKJiSw8d6A9BborherQ","supervisor_role":"whisper"}' \
  https://api.telnyx.com/v2/conferences/{id}/actions/update
Parameters
In path
id
string
required

Uniquely identifies the conference by id or name

In body (application/json)
call_control_id
string
required

Unique identifier and token for controlling the call

Example: "v2:T02llQxIyaRkhfRKxgAP8nY511EhFLizdvdUKJiSw8d6A9BborherQczRrZvZakpWxBlpw48KyZQ=="
supervisor_role
string
required

Sets the 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" ]
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"
whisper_call_control_ids
array of string
optional

Array of unique call_control_ids the 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

Successful response upon making a conference command.

401

Unauthorized response. Happens when the current user is not a manager account.

422

Unprocessable entity

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

Leave a conferenceconferenceLeave

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

Removes a call leg from a conference and moves it back to parked state. Expected Webhooks:

  • 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":"c46e06d7-b78f-4b13-96b6-c576af9640ff","beep_enabled":"never"}' \
  https://api.telnyx.com/v2/conferences/{id}/actions/leave
Parameters
In path
id
string
required

Uniquely identifies the conference by id or name

In body (application/json)
call_control_id
string
required

Unique identifier and token for controlling the call

Example: "f91269aa-61d1-417f-97b3-10e020e8bc47"
beep_enabled
string
optional

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

Example: "on_exit"
Options: [ "always", "never", "on_enter", "on_exit" ]
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"
Responses
200

Successful response upon making a conference command.

401

Unauthorized response. Happens when the current user is not a manager account.

422

Unprocessable entity

Success Response
{
  "data": {
    "result": "ok"
  }
}
Expected Webhooks
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": "v2:T02llQxIyaRkhfRKxgAP8nY511EhFLizdvdUKJiSw8d6A9BborherQ",
      "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"
  }
}

Was this section helpful?