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

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

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

Successful response with details about a conference.

401

Unauthorized

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 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}?filter[name]=global_meeting&page[size]=10"
Parameters
In path
id
string
required

Uniquely identifies the conference by id or name

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
call_control_id
string
required

Unique identifier and token for controlling the call

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

Successful response upon making a conference command.

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

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

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

Successful response upon making a conference command.

401

Unauthorized

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

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

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
audio_url
string
required

The URL of the file to be played back in the conference. The URL can point to either a WAV or MP3 file.

Example: "http://www.example.com/sounds/greeting.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
Responses
200

Successful response upon making a conference command.

401

Unauthorized

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_url": "https://www.example.com/audio.mp3",
      "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_url": "https://www.example.com/audio.mp3",
      "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_url": "https://www.example.com/audio.mp3",
      "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_url": "https://www.example.com/audio.mp3",
      "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
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"
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

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

404

Conference does not exist

422

Unprocessable entity

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

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