Conference Commands V1

Conference Command operations V1

Create a conference

Creates a conference on demand 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.

SecuritybasicAuth or bearerAuth
Request
Request Body schema: application/json
required
call_control_id
required
string

Unique identifier and token for controlling the call

name
required
string

Name of the conference

beep_enabled
string
Default: "never"

Whether a beep sound should be played to existing participants when another participant joins and/or leaves the conference. Defaults to "never".

Enum: "always" "never" "on_enter" "on_exit"
client_state
string

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

comfort_noise
boolean
Default: true

Toggle background comfort noise.

command_id
string

Use this field to avoid duplicate commands. Telnyx will ignore commands with the same "command_id".

duration_minutes
integer

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

hold_audio_url
string

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

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

Response Schema: application/json
object (ConferenceResponse)
id
required
string

Unique identifier of the conference

name
required
string

Name of the conference

created_at
required
string

ISO 8601 formatted date of when the conference was created

expires_at
required
string

ISO 8601 formatted date of when the conference will expire

401

Unauthorized

422

Unprocessable entity. Can be caused by improper use of filters or nodes.

post/conferences
Request samples
application/json
{
  • "call_control_id": "AgDIxmoRX6QMuaIj_uXRXnPAXP0QlNfXczRrZvZakpWxBlpw48KyZQ==",
  • "name": "Business",
  • "beep_enabled": "on_exit",
  • "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
  • "comfort_noise": false,
  • "command_id": "891510ac-f3e4-11e8-af5b-de00688a4901",
  • "duration_minutes": 5,
  • "hold_audio_url": "http://www.example.com/audio.wav",
  • "start_conference_on_create": false
}
Response samples
application/json
{
  • "data": {
    • "id": "string",
    • "name": "string",
    • "created_at": "string",
    • "expires_at": "string"
    }
}

List all conferences

Lists conferences belonging to the user. 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.

SecuritybasicAuth or bearerAuth
Request
query Parameters
name
string

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

page[page]
integer
Default: 1

Page number of results to load

page[page_size]
integer <= 1000
Default: 20

Number of results per page

Responses
200

Conference response

Response Schema: application/json
Array of objects (ConferenceResponse)
object (Metadata)
401

Unauthorized

422

Unprocessable entity. Can be caused by improper use of filters or nodes.

get/conferences
Request samples 
Response samples 
application/json
{
  • "data": [
    • {
      • "id": "string",
      • "name": "string",
      • "created_at": "string",
      • "expires_at": "string"
      }
    ],
  • "meta": {
    • "total_pages": 13,
    • "total_results": 13,
    • "page_number": 3,
    • "page_size": 1
    }
}
Join a conference
Joins 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.


SecuritybasicAuth or bearerAuth 
Request 
path Parameters
id
required
string
Unique identifier of the conference


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


 
command_id
string
Use this field to avoid duplicate commands. Telnyx will ignore commands with the same "command_id".


 
end_conference_on_exit
boolean
Whether the conference should end and all remaining participant 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 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".


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


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


 
supervisor_role
string
"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: "whisper" "barge" "monitor" "none"  
whisper_call_control_ids
Array of strings
Array of unique call_control_ids that for which the joining supervisor role can whisper to. If none provided, the supervisor will join the conference as a monitoring participant only.


 
Responses 
200
Successful response


Response Schema: application/json
result
required
string
 
401
Unauthorized


422
Unprocessable entity. Can be caused by improper use of filters or nodes.


post/conferences/{id}/actions/join
Request samples 
application/json
{
  • "call_control_id": "AgDIxmoRX6QMuaIj_uXRXnPAXP0QlNfXczRrZvZakpWxBlpw48KyZQ==",
  • "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:Sg1xyxQ_U3ixyxyXT_VDNI3xyxazZdg6Vxyxs4-GNYxyxVaJPOhFMRQ"
    ]
}
Response samples 
application/json
{
  • "result": "ok"
}
Mute a conference participant
Mute a list of participants in a conference call


SecuritybasicAuth or bearerAuth 
Request 
path Parameters
id
required
string
Unique identifier of the conference


 
Request Body schema: application/json
required
call_control_ids
Array of strings
List of unique identifiers and tokens for controlling the call. When empty all participants will be muted. An empty array targets all participants.


 
Responses 
200
Successful response


Response Schema: application/json
result
required
string
 
401
Unauthorized


404
Conference does not exist


422
Unprocessable entity. Can be caused by improper use of filters or nodes.


post/conferences/{id}/actions/mute
Request samples 
application/json
{
  • "call_control_ids": [
    • "string"
    ]
}
Response samples 
application/json
{
  • "result": "ok"
}
Unmute a conference participant
Unmute a list of participants in a conference call


SecuritybasicAuth or bearerAuth 
Request 
path Parameters
id
required
string
Unique identifier of the conference


 
Request Body schema: application/json
required
call_control_ids
Array of strings
List of unique identifiers and tokens for controlling the call. When empty all participants will be muted. An empty array targets all participants.


 
Responses 
200
Successful response


Response Schema: application/json
result
required
string
 
401
Unauthorized


404
Conference does not exist


422
Unprocessable entity. Can be caused by improper use of filters or nodes.


post/conferences/{id}/actions/unmute
Request samples 
application/json
{
  • "call_control_ids": [
    • "string"
    ]
}
Response samples 
application/json
{
  • "result": "ok"
}
Hold a conference participant
Hold a list of participants in a conference call


SecuritybasicAuth or bearerAuth 
Request 
path Parameters
id
required
string
Unique identifier of the conference


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


 
audio_url
string
The URL of the file to be played back on the call. The URL can point to either a WAV or MP3 file.


 
Responses 
200
Successful response


Response Schema: application/json
result
required
string
 
401
Unauthorized


404
Conference does not exist


422
Unprocessable entity. Can be caused by improper use of filters or nodes.


post/conferences/{id}/actions/hold
Request samples 
application/json
{}
Response samples 
application/json
{
  • "result": "ok"
}
Unhold a conference participant
Unhold a list of participants in a conference call


SecuritybasicAuth or bearerAuth 
Request 
path Parameters
id
required
string
Unique identifier of the conference


 
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


Response Schema: application/json
result
required
string
 
401
Unauthorized


404
Conference does not exist


422
Unprocessable entity. Can be caused by improper use of filters or nodes.


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