Conference Commands API

Conference command operations API

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

SecuritybearerAuth
Request
query Parameters
filter[name]
string

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

filter[status]
string

If present, conferences will be filtered by status.

Enum: "init" "in_progress" "completed"
page[number]
integer >= 1
Default: 1

The page number to load

page[size]
integer [ 1 .. 250 ]
Default: 20

The size of the page

Responses
200

Successful response with a list of conferences.

Response Schema: application/json
Array of objects (Conference)
object (PaginationMeta)
401

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

422

Unprocessable entity

get/conferences
Request samples 
import telnyx
telnyx.api_key = "YOUR_API_KEY"

telnyx.Conference.list(filter={"name":"string","status":"init"})
Response samples
application/json
{
  • "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 conference

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
SecuritybearerAuth
Request
Request Body schema: application/json
required

Create a conference

beep_enabled
string
Default: "never"

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

Enum: "always" "never" "on_enter" "on_exit"
call_control_id
required
string

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. The client_state will be updated for the creator call leg and will be used for all webhooks related to the created conference.

comfort_noise
boolean
Default: true

Toggle background comfort noise.

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.

duration_minutes
integer

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

hold_audio_url
string

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

hold_media_name
string

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

max_participants
integer

The maximum number of active conference participants to allow. Must be between 2 and 800. Defaults to 250

name
required
string

Name of the conference

start_conference_on_create
boolean

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.

Response Schema: application/json
object (Conference)
connection_id
string

Identifies the connection (Call Control App) associated with the conference

created_at
required
string

ISO 8601 formatted date of when the conference was created

end_reason
string

Reason why the conference ended

Enum: "all_left" "ended_via_api" "host_left" "time_exceeded"
object

IDs related to who ended the conference. It is expected for them to all be there or all be null

expires_at
required
string

ISO 8601 formatted date of when the conference will expire

id
required
string

Uniquely identifies the conference

name
required
string

Name of the conference

record_type
required
string
Value: "conference"
region
string

Region where the conference is hosted

status
string

Status of the conference

Enum: "init" "in_progress" "completed"
updated_at
string

ISO 8601 formatted date of when the conference was last updated

401

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

422

Unprocessable entity

Callbacks
postConference Created Post
postConference Ended Post
postConference Floor Changed Post
postConference Participant Joined Post
postConference Participant Left Post
post/conferences
Request samples
application/json
{
  • "beep_enabled": "always",
  • "call_control_id": "v3:MdI91X4lWFEs7IgbBEOT9M4AigoY08M0WWZFISt1Yw2axZ_IiE4pqg",
  • "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
  • "command_id": "891510ac-f3e4-11e8-af5b-de00688a4901",
  • "duration_minutes": 5,
  • "hold_audio_url": "http://www.example.com/audio.wav",
  • "max_participants": 250,
  • "name": "Business",
  • "start_conference_on_create": false
}
Response samples
application/json
{
  • "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"
    }
}
Callback payload samples
application/json
{
  • "data": {
    • "event_type": "conference.created",
    • "id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
    • "occurred_at": "2018-02-02T22:25:27.521992Z",
    • "payload": {
      • "call_control_id": "v3:MdI91X4lWFEs7IgbBEOT9M4AigoY08M0WWZFISt1Yw2axZ_IiE4pqg",
      • "call_leg_id": "428c31b6-7af4-4bcb-b7f5-5013ef9657c1",
      • "call_session_id": "428c31b6-7af4-4bcb-b7f5-5013ef9657c1",
      • "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
      • "conference_id": "428c31b6-abf3-3bc1-b7f4-5013ef9657c1",
      • "connection_id": "7267xxxxxxxxxxxxxx",
      • "occured_at": "2018-02-02T22:25:27.521Z"
      },
    • "record_type": "event"
    }
}

List conference participants

Lists conference participants

SecuritybearerAuth
Request
path Parameters
conference_id
required
string

Uniquely identifies the conference by id

query Parameters
filter[muted]
boolean

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

filter[on_hold]
boolean

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

filter[whispering]
boolean

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

page[number]
integer >= 1
Default: 1

The page number to load

page[size]
integer [ 1 .. 250 ]
Default: 20

The size of the page

Responses
200

Successful response with a list of conference participants.

Response Schema: application/json
Array of objects (Participant)
object (PaginationMeta)
401

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

404

Fax does not exist

422

Unprocessable entity

get/conferences/{conference_id}/participants
Request samples 
import telnyx
telnyx.api_key = "YOUR_API_KEY"

telnyx.Conferences.retrieve_participant.retrieve("conference_id",filter={"muted":"boolean","on_hold":"boolean"})
Response samples
application/json
{
  • "data": [
    • {
      • "call_control_id": "v3:MdI91X4lWFEs7IgbBEOT9M4AigoY08M0WWZFISt1Yw2axZ_IiE4pqg",
      • "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
    }
}

Retrieve a conference

Retrieve an existing conference

SecuritybearerAuth
Request
path Parameters
id
required
string

Uniquely identifies the conference by id

Responses
200

Successful response with details about a conference.

Response Schema: application/json
object (Conference)
connection_id
string

Identifies the connection (Call Control App) associated with the conference

created_at
required
string

ISO 8601 formatted date of when the conference was created

end_reason
string

Reason why the conference ended

Enum: "all_left" "ended_via_api" "host_left" "time_exceeded"
object

IDs related to who ended the conference. It is expected for them to all be there or all be null

expires_at
required
string

ISO 8601 formatted date of when the conference will expire

id
required
string

Uniquely identifies the conference

name
required
string

Name of the conference

record_type
required
string
Value: "conference"
region
string

Region where the conference is hosted

status
string

Status of the conference

Enum: "init" "in_progress" "completed"
updated_at
string

ISO 8601 formatted date of when the conference was last updated

404

Fax does not exist

get/conferences/{id}
Request samples 
const telnyx = require('telnyx')('YOUR_API_KEY');

const { data } = await telnyx.conferences.retrieve('id');
Response samples
application/json
{
  • "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"
    }
}

Hold conference participants

Hold a list of participants in a conference call

SecuritybearerAuth
Request
path Parameters
id
required
string

Uniquely identifies the conference by id or name

Request Body schema: application/json
required
audio_url
string

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.

call_control_ids
Array of strings

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

media_name
string

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.

Responses
200

Successful response upon making a conference command.

Response Schema: application/json
object (ConferenceCommandResult)
result
required
string
401

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

404

Fax does not exist

422

Unprocessable entity

post/conferences/{id}/actions/hold
Request samples
application/json
{}
Response samples
application/json
{
  • "data": {
    • "result": "ok"
    }
}

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
SecuritybearerAuth
Request
path Parameters
id
required
string

Uniquely identifies the conference by id or name

Request Body schema: application/json
required

Join Conference request object

beep_enabled
string

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.

Enum: "always" "never" "on_enter" "on_exit"
call_control_id
required
string

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

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

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

start_conference_on_enter
boolean

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

supervisor_role
string

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

Enum: "barge" "monitor" "none" "whisper"
whisper_call_control_ids
Array of strings

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.

Responses
200

Successful response upon making a conference command.

Response Schema: application/json
object (ConferenceCommandResult)
result
required
string
401

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

422

Unprocessable entity

Callbacks
postParticipant Joined Post
postParticipant Left Post
post/conferences/{id}/actions/join
Request samples
application/json
{
  • "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 samples
application/json
{
  • "data": {
    • "result": "ok"
    }
}
Callback payload samples
application/json
{
  • "data": {
    • "event_type": "conference.participant.joined",
    • "id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
    • "occurred_at": "2018-02-02T22:25:27.521992Z",
    • "payload": {
      • "call_control_id": "v3:MdI91X4lWFEs7IgbBEOT9M4AigoY08M0WWZFISt1Yw2axZ_IiE4pqg",
      • "call_leg_id": "428c31b6-7af4-4bcb-b7f5-5013ef9657c1",
      • "call_session_id": "428c31b6-7af4-4bcb-b7f5-5013ef9657c1",
      • "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
      • "conference_id": "428c31b6-abf3-3bc1-b7f4-5013ef9657c1",
      • "connection_id": "7267xxxxxxxxxxxxxx"
      },
    • "record_type": "event"
    }
}

Leave a conference

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

  • conference.participant.left
SecuritybearerAuth
Request
path Parameters
id
required
string

Uniquely identifies the conference by id or name

Request Body schema: application/json
required

Leave Conference request object

beep_enabled
string

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

Enum: "always" "never" "on_enter" "on_exit"
call_control_id
required
string

Unique identifier and token for controlling the call

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.

Responses
200

Successful response upon making a conference command.

Response Schema: application/json
object (ConferenceCommandResult)
result
required
string
401

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

422

Unprocessable entity

Callbacks
postParticipant Left Post
post/conferences/{id}/actions/leave
Request samples
application/json
{
  • "beep_enabled": "never",
  • "call_control_id": "c46e06d7-b78f-4b13-96b6-c576af9640ff"
}
Response samples
application/json
{
  • "data": {
    • "result": "ok"
    }
}
Callback payload samples
POST: Participant Left Post
application/json
{
  • "data": {
    • "event_type": "conference.participant.left",
    • "id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
    • "occurred_at": "2018-02-02T22:25:27.521992Z",
    • "payload": {
      • "call_control_id": "v3:MdI91X4lWFEs7IgbBEOT9M4AigoY08M0WWZFISt1Yw2axZ_IiE4pqg",
      • "call_leg_id": "428c31b6-7af4-4bcb-b7f5-5013ef9657c1",
      • "call_session_id": "428c31b6-7af4-4bcb-b7f5-5013ef9657c1",
      • "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
      • "conference_id": "428c31b6-abf3-3bc1-b7f4-5013ef9657c1",
      • "connection_id": "7267xxxxxxxxxxxxxx"
      },
    • "record_type": "event"
    }
}

Mute conference participants

Mute a list of participants in a conference call

SecuritybearerAuth
Request
path Parameters
id
required
string

Uniquely identifies the conference by id or name

Request Body schema: application/json
required
call_control_ids
Array of strings

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.

Response Schema: application/json
object (ConferenceCommandResult)
result
required
string
401

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

404

Fax does not exist

422

Unprocessable entity

post/conferences/{id}/actions/mute
Request samples
application/json
{
  • "call_control_ids": [
    • "v3:MdI91X4lWFEs7IgbBEOT9M4AigoY08M0WWZFISt1Yw2axZ_IiE4pqg"
    ]
}
Response samples
application/json
{
  • "data": {
    • "result": "ok"
    }
}

Play audio to conference participants

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

SecuritybearerAuth
Request
path Parameters
id
required
string

Uniquely identifies the conference by id or name

Request Body schema: application/json
required
audio_url
string

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

call_control_ids
Array of strings

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.

string or integer (Loopcount)
media_name
string

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.

Responses
200

Successful response upon making a conference command.

Response Schema: application/json
object (ConferenceCommandResult)
result
required
string
401

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

404

Fax does not exist

422

Unprocessable entity

Callbacks
postParticipant Playback Ended Post
postParticipant Playback Started Post
postPlayback Ended Post
postPlayback Started Post
post/conferences/{id}/actions/play
Request samples
application/json
{}
Response samples
application/json
{
  • "data": {
    • "result": "ok"
    }
}
Callback payload samples
application/json
{
  • "data": {
    • "event_type": "conference.participant.playback.ended",
    • "id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
    • "occurred_at": "2018-02-02T22:25:27.521992Z",
    • "payload": {
      • "call_control_id": "v3:MdI91X4lWFEs7IgbBEOT9M4AigoY08M0WWZFISt1Yw2axZ_IiE4pqg",
      • "call_leg_id": "428c31b6-7af4-4bcb-b7f5-5013ef9657c1",
      • "call_session_id": "428c31b6-7af4-4bcb-b7f5-5013ef9657c1",
      • "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
      • "conference_id": "428c31b6-abf3-3bc1-b7f4-5013ef9657c1",
      • "connection_id": "7267xxxxxxxxxxxxxx",
      • "creator_call_session_id": "428c31b6-7af4-4bcb-b7f5-5013ef9657c1",
      • "media_url": "https://www.example.com/audio.mp3",
      • "occured_at": "2018-02-02T22:25:27.521Z"
      },
    • "record_type": "event"
    }
}

Conference recording pause

Pause conference recording.

SecuritybearerAuth
Request
path Parameters
id
required
string

Specifies the conference by id or name

Request Body schema: application/json
required
command_id
string

Use this field to avoid duplicate commands. Telnyx will ignore any command with the same command_id for the same call_control_id.

recording_id
string

Use this field to pause specific recording.

Responses
200

Successful response upon making a conference command.

Response Schema: application/json
object (ConferenceCommandResult)
result
required
string
401

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

404

Fax does not exist

422

Unprocessable entity

post/conferences/{id}/actions/record_pause
Request samples
application/json
{
  • "command_id": "891510ac-f3e4-11e8-af5b-de00688a4901",
  • "recording_id": "891510ac-f3e4-11e8-af5b-de00688a4901"
}
Response samples
application/json
{
  • "data": {
    • "result": "ok"
    }
}

Conference recording resume

Resume conference recording.

SecuritybearerAuth
Request
path Parameters
id
required
string

Specifies the conference by id or name

Request Body schema: application/json
required
command_id
string

Use this field to avoid duplicate commands. Telnyx will ignore any command with the same command_id for the same call_control_id.

recording_id
string

Use this field to resume specific recording.

Responses
200

Successful response upon making a conference command.

Response Schema: application/json
object (ConferenceCommandResult)
result
required
string
401

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

404

Fax does not exist

422

Unprocessable entity

post/conferences/{id}/actions/record_resume
Request samples
application/json
{
  • "command_id": "891510ac-f3e4-11e8-af5b-de00688a4901",
  • "recording_id": "891510ac-f3e4-11e8-af5b-de00688a4901"
}
Response samples
application/json
{
  • "data": {
    • "result": "ok"
    }
}

Conference recording start

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

Expected Webhooks:

  • conference.recording.saved
SecuritybearerAuth
Request
path Parameters
id
required
string

Specifies the conference to record by id or name

Request Body schema: application/json
required
channels
required
string

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

Enum: "single" "dual"
client_state
string

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

command_id
string

Use this field to avoid duplicate commands. Telnyx will ignore any command with the same command_id for the same call_control_id.

format
required
string

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

Enum: "wav" "mp3"
max_length
integer <int32>
Default: 0

Defines the maximum length for the recording in seconds. The minimum value is 0. The maximum value is 14400. The default value is 0 (infinite)

play_beep
boolean

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

timeout_secs
integer <int32>
Default: 0

The number of seconds that Telnyx will wait for the recording to be stopped if silence is detected. The timer only starts when the speech is detected. The minimum value is 0. The default value is 0 (infinite). Please note that the transcription is being used for detecting the silence and the charge for it will be applied.

Responses
200

Successful response upon making a conference command.

Response Schema: application/json
object (ConferenceCommandResult)
result
required
string
401

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

404

Fax does not exist

422

Unprocessable entity

post/conferences/{id}/actions/record_start
Request samples
application/json
{
  • "channels": "single",
  • "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
  • "command_id": "891510ac-f3e4-11e8-af5b-de00688a4901",
  • "format": "wav",
  • "max_length": 0,
  • "play_beep": true,
  • "timeout_secs": 0
}
Response samples
application/json
{
  • "data": {
    • "result": "ok"
    }
}

Conference recording stop

Stop recording the conference.

Expected Webhooks:

  • conference.recording.saved
SecuritybearerAuth
Request
path Parameters
id
required
string

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

Request Body schema: application/json
required

Stop recording conference request

client_state
string

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

command_id
string

Use this field to avoid duplicate commands. Telnyx will ignore any command with the same command_id for the same call_control_id.

Responses
200

Successful response upon making a conference command.

Response Schema: application/json
object (ConferenceCommandResult)
result
required
string
401

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

404

Fax does not exist

422

Unprocessable entity

Callbacks
postRecording Saved Post
post/conferences/{id}/actions/record_stop
Request samples
application/json
{
  • "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
  • "command_id": "891510ac-f3e4-11e8-af5b-de00688a4901"
}
Response samples
application/json
{
  • "data": {
    • "result": "ok"
    }
}
Callback payload samples
POST: Recording Saved Post
application/json
{
  • "data": {
    • "event_type": "conference.recording.saved",
    • "id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
    • "occurred_at": "2018-02-02T22:25:27.521992Z",
    • "payload": {
      • "call_control_id": "v3:MdI91X4lWFEs7IgbBEOT9M4AigoY08M0WWZFISt1Yw2axZ_IiE4pqg",
      • "call_session_id": "428c31b6-7af4-4bcb-b7f5-5013ef9657c1",
      • "channels": "single",
      • "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
      • "conference_id": "428c31b6-abf3-3bc1-b7f4-5013ef9657c1",
      • "connection_id": "7267xxxxxxxxxxxxxx",
      • "format": "mp3",
      • "public_recording_urls": {},
      • "recording_ended_at": "2018-02-02T22:20:27.521992Z",
      • "recording_id": "4577f9a2-cf0e-44f3-ac57-9f95fb03fa47",
      • "recording_started_at": "2021-05-11T10:17:03.692107Z",
      • "recording_urls": {}
      },
    • "record_type": "event"
    }
}

Speak text to conference participants

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

SecuritybearerAuth
Request
path Parameters
id
required
string

Specifies the conference by id or name

Request Body schema: application/json
required
call_control_ids
Array of strings

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

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.

language
required
string

The language used to speak the text.

Enum: "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
required
string

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

payload_type
string
Default: "text"

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

Enum: "text" "ssml"
voice
required
string

The gender of the voice used to speak the text.

Enum: "male" "female"
Responses
200

Successful response upon making a conference command.

Response Schema: application/json
object (ConferenceCommandResult)
result
required
string
401

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

404

Fax does not exist

422

Unprocessable entity

Callbacks
postParticipant Speak Ended Post
postParticipant Speak Started Post
postSpeak Ended Post
postSpeak Started Post
post/conferences/{id}/actions/speak
Request samples
application/json
{
  • "call_control_ids": [
    • "v3:MdI91X4lWFEs7IgbBEOT9M4AigoY08M0WWZFISt1Yw2axZ_IiE4pqg"
    ],
  • "command_id": "891510ac-f3e4-11e8-af5b-de00688a4901",
  • "language": "en-US",
  • "payload": "Say this to participants",
  • "payload_type": "text",
  • "voice": "female"
}
Response samples
application/json
{
  • "data": {
    • "result": "ok"
    }
}
Callback payload samples
application/json
{
  • "data": {
    • "event_type": "conference.participant.speak.ended",
    • "id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
    • "occurred_at": "2018-02-02T22:25:27.521992Z",
    • "payload": {
      • "call_control_id": "v3:MdI91X4lWFEs7IgbBEOT9M4AigoY08M0WWZFISt1Yw2axZ_IiE4pqg",
      • "call_leg_id": "428c31b6-7af4-4bcb-b7f5-5013ef9657c1",
      • "call_session_id": "428c31b6-7af4-4bcb-b7f5-5013ef9657c1",
      • "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
      • "conference_id": "428c31b6-abf3-3bc1-b7f4-5013ef9657c1",
      • "connection_id": "7267xxxxxxxxxxxxxx",
      • "creator_call_session_id": "428c31b6-7af4-4bcb-b7f5-5013ef9657c1",
      • "occured_at": "2018-02-02T22:25:27.521Z"
      },
    • "record_type": "event"
    }
}

Stop audio being played on the conference

Stop audio being played to all or some participants on a conference call.

SecuritybearerAuth
Request
path Parameters
id
required
string

Uniquely identifies the conference by id or name

Request Body schema: application/json
required
call_control_ids
Array of strings

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.

Response Schema: application/json
object (ConferenceCommandResult)
result
required
string
401

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

404

Fax does not exist

422

Unprocessable entity

Callbacks
postParticipant Playback Ended Post
post/conferences/{id}/actions/stop
Request samples
application/json
{
  • "call_control_ids": [
    • "string"
    ]
}
Response samples
application/json
{
  • "data": {
    • "result": "ok"
    }
}
Callback payload samples
POST: Participant Playback Ended Post
application/json
{
  • "data": {
    • "event_type": "conference.participant.playback.ended",
    • "id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
    • "occurred_at": "2018-02-02T22:25:27.521992Z",
    • "payload": {
      • "call_control_id": "v3:MdI91X4lWFEs7IgbBEOT9M4AigoY08M0WWZFISt1Yw2axZ_IiE4pqg",
      • "call_leg_id": "428c31b6-7af4-4bcb-b7f5-5013ef9657c1",
      • "call_session_id": "428c31b6-7af4-4bcb-b7f5-5013ef9657c1",
      • "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
      • "conference_id": "428c31b6-abf3-3bc1-b7f4-5013ef9657c1",
      • "connection_id": "7267xxxxxxxxxxxxxx",
      • "creator_call_session_id": "428c31b6-7af4-4bcb-b7f5-5013ef9657c1",
      • "media_url": "https://www.example.com/audio.mp3",
      • "occured_at": "2018-02-02T22:25:27.521Z"
      },
    • "record_type": "event"
    }
}

Unhold conference participants

Unhold a list of participants in a conference call

SecuritybearerAuth
Request
path Parameters
id
required
string

Uniquely identifies the conference by id or name

Request Body schema: application/json
required
call_control_ids
required
Array of strings

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.

Response Schema: application/json
object (ConferenceCommandResult)
result
required
string
401

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

404

Fax does not exist

422

Unprocessable entity

post/conferences/{id}/actions/unhold
Request samples
application/json
{
  • "call_control_ids": [
    • "v3:MdI91X4lWFEs7IgbBEOT9M4AigoY08M0WWZFISt1Yw2axZ_IiE4pqg"
    ]
}
Response samples
application/json
{
  • "data": {
    • "result": "ok"
    }
}

Unmute conference participants

Unmute a list of participants in a conference call

SecuritybearerAuth
Request
path Parameters
id
required
string

Uniquely identifies the conference by id or name

Request Body schema: application/json
required
call_control_ids
Array of strings

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.

Response Schema: application/json
object (ConferenceCommandResult)
result
required
string
401

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

404

Fax does not exist

422

Unprocessable entity

post/conferences/{id}/actions/unmute
Request samples
application/json
{
  • "call_control_ids": [
    • "v3:MdI91X4lWFEs7IgbBEOT9M4AigoY08M0WWZFISt1Yw2axZ_IiE4pqg"
    ]
}
Response samples
application/json
{
  • "data": {
    • "result": "ok"
    }
}

Update conference participant

Update conference participant supervisor_role

SecuritybearerAuth
Request
path Parameters
id
required
string

Uniquely identifies the conference by id or name

Request Body schema: application/json
required

Update Conference request object

call_control_id
required
string

Unique identifier and token for controlling the call

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.

supervisor_role
required
string

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

Enum: "barge" "monitor" "none" "whisper"
whisper_call_control_ids
Array of strings

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.

Responses
200

Successful response upon making a conference command.

Response Schema: application/json
object (ConferenceCommandResult)
result
required
string
401

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

422

Unprocessable entity

post/conferences/{id}/actions/update
Request samples
application/json
{
  • "call_control_id": "v3:MdI91X4lWFEs7IgbBEOT9M4AigoY08M0WWZFISt1Yw2axZ_IiE4pqg",
  • "command_id": "891510ac-f3e4-11e8-af5b-de00688a4901",
  • "supervisor_role": "whisper",
  • "whisper_call_control_ids": [
    • "v2:Sg1xxxQ_U3ixxxyXT_VDNI3xxxazZdg6Vxxxs4-GNYxxxVaJPOhFMRQ",
    • "v2:qqpb0mmvd-ovhhBr0BUQQn0fld5jIboaaX3-De0DkqXHzbf8d75xkw"
    ]
}
Response samples
application/json
{
  • "data": {
    • "result": "ok"
    }
}