OpenAPI Specification
openapi: 3.1.0
info:
contact:
email: support@telnyx.com
description: Telnyx provides global communications and connectivity APIs for developers — including SIP trunking, programmable voice, SMS, MMS, WhatsApp Business Messaging, Call Control, Fax, Wireless (IoT & eSIM), Phone Numbers (DID provisioning & porting), Emergency Services, and Network APIs for private interconnects and edge connectivity. Build, scale, and manage voice, messaging, and data networks with Telnyx's carrier-grade global infrastructure and API-first platform.
title: Telnyx Access Tokens Queue Commands API
version: 2.0.0
x-endpoint-cost: light
servers:
- description: Version 2.0.0 of the Telnyx API
url: https://api.telnyx.com/v2
security:
- bearerAuth: []
tags:
- description: Queue commands operations
name: Queue Commands
paths:
/queues:
get:
description: List all queues for the authenticated user.
operationId: ListQueues
parameters:
- description: The page number to load
in: query
name: page[number]
required: false
schema:
default: 1
minimum: 1
type: integer
- description: The size of the page
in: query
name: page[size]
required: false
schema:
default: 20
maximum: 250
minimum: 1
type: integer
responses:
'200':
$ref: '#/components/responses/ListQueuesResponse'
'401':
$ref: '#/components/responses/UnauthorizedResponse'
'422':
$ref: '#/components/responses/UnprocessableEntityResponse'
summary: List queues
tags:
- Queue Commands
x-latency-category: interactive
post:
description: Create a new call queue.
operationId: CreateQueue
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateQueueRequest'
responses:
'200':
$ref: '#/components/responses/QueueResponse'
'401':
$ref: '#/components/responses/UnauthorizedResponse'
'422':
$ref: '#/components/responses/UnprocessableEntityResponse'
summary: Create a queue
tags:
- Queue Commands
x-latency-category: interactive
/queues/{queue_name}:
delete:
description: Delete an existing call queue.
operationId: DeleteQueue
parameters:
- description: Uniquely identifies the queue by name
in: path
name: queue_name
required: true
schema:
type: string
responses:
'204':
description: Queue deleted successfully.
'401':
$ref: '#/components/responses/UnauthorizedResponse'
'404':
$ref: '#/components/responses/NotFoundResponse'
summary: Delete a queue
tags:
- Queue Commands
x-latency-category: interactive
get:
description: Retrieve an existing call queue
operationId: RetrieveCallQueue
parameters:
- description: Uniquely identifies the queue by name
in: path
name: queue_name
required: true
schema:
type: string
responses:
'200':
$ref: '#/components/responses/QueueResponse'
'404':
$ref: '#/components/responses/NotFoundResponse'
summary: Retrieve a call queue
tags:
- Queue Commands
x-latency-category: interactive
post:
description: Update properties of an existing call queue.
operationId: UpdateQueue
parameters:
- description: Uniquely identifies the queue by name
in: path
name: queue_name
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateQueueRequest'
responses:
'200':
$ref: '#/components/responses/QueueResponse'
'401':
$ref: '#/components/responses/UnauthorizedResponse'
'404':
$ref: '#/components/responses/NotFoundResponse'
'422':
$ref: '#/components/responses/UnprocessableEntityResponse'
summary: Update a queue
tags:
- Queue Commands
x-latency-category: interactive
/queues/{queue_name}/calls:
get:
description: Retrieve the list of calls in an existing queue
operationId: ListQueueCalls
parameters:
- description: Uniquely identifies the queue by name
in: path
name: queue_name
required: true
schema:
type: string
- $ref: '#/components/parameters/call-control_PageConsolidated'
responses:
'200':
$ref: '#/components/responses/ListQueueCallsResponse'
'404':
$ref: '#/components/responses/NotFoundResponse'
summary: Retrieve calls from a queue
tags:
- Queue Commands
x-latency-category: interactive
/queues/{queue_name}/calls/{call_control_id}:
delete:
description: Removes an inactive call from a queue. If the call is no longer active, use this command to remove it from the queue.
operationId: RemoveQueueCall
parameters:
- description: Uniquely identifies the queue by name
in: path
name: queue_name
required: true
schema:
type: string
- $ref: '#/components/parameters/CallControlId'
responses:
'204':
description: Call successfully removed from the queue
'404':
$ref: '#/components/responses/NotFoundResponse'
summary: Force remove a call from a queue
tags:
- Queue Commands
x-latency-category: interactive
get:
description: Retrieve an existing call from an existing queue
operationId: RetrieveCallFromQueue
parameters:
- description: Uniquely identifies the queue by name
in: path
name: queue_name
required: true
schema:
type: string
- $ref: '#/components/parameters/CallControlId'
responses:
'200':
$ref: '#/components/responses/QueueCallResponse'
'404':
$ref: '#/components/responses/NotFoundResponse'
summary: Retrieve a call from a queue
tags:
- Queue Commands
x-latency-category: interactive
patch:
description: Update queued call's keep_after_hangup flag
operationId: UpdateCallInQueue
parameters:
- description: Uniquely identifies the queue by name
in: path
name: queue_name
required: true
schema:
type: string
- $ref: '#/components/parameters/CallControlId'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateQueuedCallRequest'
description: Update queued call request.
required: true
responses:
'204':
description: Call has been successfully updated.
'404':
$ref: '#/components/responses/NotFoundResponse'
summary: Update queued call
tags:
- Queue Commands
x-latency-category: interactive
components:
schemas:
UpdateQueueRequest:
example:
max_size: 200
properties:
max_size:
description: The maximum number of calls allowed in the queue.
example: 200
minimum: 1
type: integer
required:
- max_size
title: Update Queue Request
type: object
Queue:
example:
average_wait_time_secs: 175
created_at: '2019-01-23T18:10:02.574Z'
current_size: 20
id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
max_size: 50
name: support
record_type: queue
updated_at: '2019-01-23T18:10:02.574Z'
properties:
average_wait_time_secs:
description: The average time that the calls currently in the queue have spent waiting, given in seconds.
example: 175
type: integer
created_at:
description: ISO 8601 formatted date of when the queue was created
example: '2019-01-23T18:10:02.574Z'
type: string
current_size:
description: The number of calls currently in the queue
example: 20
type: integer
id:
description: Uniquely identifies the queue
example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
type: string
max_size:
description: The maximum number of calls allowed in the queue
example: 50
type: integer
name:
description: Name of the queue
example: support
type: string
record_type:
enum:
- queue
example: queue
type: string
updated_at:
description: ISO 8601 formatted date of when the queue was last updated
example: '2019-01-23T18:10:02.574Z'
type: string
required:
- record_type
- id
- name
- current_size
- max_size
- average_wait_time_secs
- created_at
- updated_at
title: Queue
type: object
CreateQueueRequest:
example:
max_size: 100
queue_name: tier_1_support
properties:
max_size:
default: 300
description: The maximum number of calls allowed in the queue.
example: 100
minimum: 1
type: integer
queue_name:
description: The name of the queue. Must be between 1 and 255 characters.
example: tier_1_support
maxLength: 255
minLength: 1
type: string
required:
- queue_name
title: Create Queue Request
type: object
PaginationMeta:
properties:
page_number:
example: 2
type: integer
page_size:
example: 25
type: integer
total_pages:
example: 3
type: integer
total_results:
example: 55
type: integer
type: object
call-control_Errors:
properties:
errors:
items:
$ref: '#/components/schemas/call-control_Error'
type: array
QueueCall:
example:
call_control_id: v3:MdI91X4lWFEs7IgbBEOT9M4AigoY08M0WWZFISt1Yw2axZ_IiE4pqg
call_leg_id: 2dc6fc34-f9e0-11ea-b68e-02420a0f7768
call_session_id: 2dc1b3c8-f9e0-11ea-bc5a-02420a0f7768
connection_id: 7267xxxxxxxxxxxxxx
enqueued_at: '2019-01-23T18:10:02.574Z'
from: '+18005550101'
is_alive: true
queue_id: ae1626cc-6f42-11ea-becd-02420a0f8b69
queue_position: 3
record_type: queue_call
to: '+18005550102'
wait_time_secs: 145
properties:
call_control_id:
description: Unique identifier and token for controlling the call.
example: v3:MdI91X4lWFEs7IgbBEOT9M4AigoY08M0WWZFISt1Yw2axZ_IiE4pqg
type: string
call_leg_id:
description: ID that is unique to the call and can be used to correlate webhook events
example: 428c31b6-7af4-4bcb-b7f5-5013ef9657c1
type: string
call_session_id:
description: ID that is unique to the call session and can be used to correlate webhook events. Call session is a group of related call legs that logically belong to the same phone call, e.g. an inbound and outbound leg of a transferred call
example: 428c31b6-7af4-4bcb-b68e-5013ef9657c1
type: string
connection_id:
description: Call Control App ID (formerly Telnyx connection ID) used in the call.
example: 7267xxxxxxxxxxxxxx
type: string
enqueued_at:
description: ISO 8601 formatted date of when the call was put in the queue
example: '2019-01-23T18:10:02.574Z'
type: string
from:
description: Number or SIP URI placing the call.
example: '+35319605860'
type: string
is_alive:
description: Indicates whether the call is still active in the queue.
example: true
type: boolean
queue_id:
description: Unique identifier of the queue the call is in.
example: ae1626cc-6f42-11ea-becd-02420a0f8b69
type: string
queue_position:
description: Current position of the call in the queue
example: 3
type: integer
record_type:
enum:
- queue_call
example: queue_call
type: string
to:
description: Destination number or SIP URI of the call.
example: '+13129457420'
type: string
wait_time_secs:
description: The time the call has been waiting in the queue, given in seconds
example: 272
type: integer
required:
- call_control_id
- call_leg_id
- call_session_id
- is_alive
- record_type
- connection_id
- from
- to
- enqueued_at
- wait_time_secs
- queue_position
- queue_id
title: QueueCall
type: object
call-control_Error:
properties:
code:
format: integer
type: string
detail:
type: string
meta:
type: object
source:
properties:
parameter:
description: Indicates which query parameter caused the error.
type: string
pointer:
description: JSON pointer (RFC6901) to the offending entity.
format: json-pointer
type: string
type: object
title:
type: string
required:
- code
- title
UpdateQueuedCallRequest:
example:
keep_after_hangup: true
properties:
keep_after_hangup:
description: Whether the call should remain in queue after hangup.
example: true
type: boolean
title: Update Queued Call Request
type: object
responses:
NotFoundResponse:
content:
application/json:
examples:
audio_file_not_found:
summary: Audio file not found
value:
errors:
- code: '10005'
detail: Provided audio file URL couldn't be found.
title: Audio file not found
conference_not_found:
summary: Conference not found
value:
errors:
- code: '90058'
detail: The conference does not exist.
title: Invalid conference_id
recording_not_found:
summary: Recording not found
value:
errors:
- code: '10005'
detail: The recording could not be found. Please check the recording_id and try again.
source:
pointer: /recording_id
title: Recording not found
resource_not_found:
summary: Generic resource not found
value:
errors:
- code: '10007'
detail: Resource not found
title: Resource not found
schema:
$ref: '#/components/schemas/call-control_Errors'
description: 'Resource not found. The requested resource does not exist. Common causes include: invalid call_control_id, conference not found, audio file not found, or recording not found.'
ListQueuesResponse:
content:
application/json:
schema:
properties:
data:
items:
$ref: '#/components/schemas/Queue'
type: array
meta:
$ref: '#/components/schemas/PaginationMeta'
title: List Queues Response
type: object
description: Successful response with a list of queues.
ListQueueCallsResponse:
content:
application/json:
schema:
properties:
data:
items:
$ref: '#/components/schemas/QueueCall'
type: array
meta:
$ref: '#/components/schemas/PaginationMeta'
title: List Queue Calls Response
type: object
description: Successful response with a list of calls in a queue.
QueueResponse:
content:
application/json:
schema:
properties:
data:
$ref: '#/components/schemas/Queue'
title: Queue Response
type: object
description: Successful response with details about a queue.
QueueCallResponse:
content:
application/json:
schema:
properties:
data:
$ref: '#/components/schemas/QueueCall'
title: Queue Call Response
type: object
description: Successful response with details about a call in a queue.
UnprocessableEntityResponse:
content:
application/json:
examples:
ai_assistant_already_active:
summary: AI Assistant already active
value:
errors:
- code: '90061'
detail: AI Assistant cannot be started more than once.
title: AI Assistant is already in progress
call_already_ended:
summary: Call has already ended
value:
errors:
- code: '90018'
detail: This call is no longer active and can't receive commands.
title: Call has already ended
call_already_in_queue:
summary: Call already in queue
value:
errors:
- code: '90038'
detail: Call can't be added to a queue it's already in.
title: Call already in queue
call_not_answered:
summary: Call not answered yet
value:
errors:
- code: '90034'
detail: This call can't receive this command because it has not been answered yet.
title: Call not answered yet
cannot_record_before_audio_started:
summary: Cannot record before audio started
value:
errors:
- code: '90020'
detail: Call recording cannot be started until audio has commenced on the call.
title: Call recording triggered before audio started
conference_already_ended:
summary: Conference has already ended
value:
errors:
- code: '90019'
detail: This conference is no longer active and can't receive commands.
title: Conference has already ended
conference_name_conflict:
summary: Conference name conflict
value:
errors:
- code: '90033'
detail: Conference with given name already exists and it's active.
title: Unable to execute command
fork_not_found:
summary: Call is not forked
value:
errors:
- code: '90031'
detail: Can't stop forking, because the call isn't currently forked.
title: Call is not currently forked
invalid_call_control_id:
summary: Invalid call control ID
value:
errors:
- code: '90015'
detail: The call_control_id provided was not valid.
source:
pointer: /call_control_id
title: Invalid Call Control ID
invalid_connection_id:
summary: Invalid connection ID
value:
errors:
- code: '10015'
detail: The requested connection_id (Call Control App ID) is either invalid or does not exist. Only Call Control Apps with valid webhook URL are accepted.
source:
pointer: /connection_id
title: Invalid value for connection_id (Call Control App ID)
invalid_enumerated_value:
summary: Invalid enumerated value
value:
errors:
- code: '10032'
detail: 'The value must be one of: dual, single.'
source:
pointer: /record_channels
title: Invalid enumerated value
invalid_phone_number_format:
summary: Invalid phone number format
value:
errors:
- code: '10016'
detail: The 'to' parameter must be in E164 format.
source:
pointer: /to
title: Phone number must be in +E164 format
max_participants_reached:
summary: Maximum participants reached
value:
errors:
- code: '90032'
detail: The maximum allowed value of `max_participants` has been reached at 100.
title: Maximum number of participants reached
media_streaming_used:
summary: Media streaming in use
value:
errors:
- code: '90045'
detail: This command can't be issued when media streaming is used.
title: Media Streaming is used
missing_required_parameter:
summary: Missing required parameter
value:
errors:
- code: '10004'
detail: The 'to' parameter is required and cannot be blank.
source:
pointer: /to
title: Missing required parameter
queue_full:
summary: Queue is full
value:
errors:
- code: '90036'
detail: The 'support' queue is full and can't accept more calls.
title: Queue full
srtp_not_supported_for_pstn:
summary: SRTP not supported for PSTN calls
value:
errors:
- code: '10011'
detail: SRTP media encryption is not supported for PSTN calls.
source:
pointer: /media_encryption
title: Media encryption not supported for PSTN calls
transcription_already_active:
summary: Transcription already active
value:
errors:
- code: '90054'
detail: Call transcription can not be started more than once.
title: Call transcription is already in progress
value_outside_range:
summary: Value outside of range
value:
errors:
- code: '10033'
detail: The value is outside of allowed range 1 to 5000
source:
pointer: /max_participants
title: Value outside of range
schema:
$ref: '#/components/schemas/call-control_Errors'
description: Unprocessable entity. The request was well-formed but could not be processed due to semantic errors. This includes validation errors, invalid parameter values, call state errors, conference errors, queue errors, recording/transcription errors, and business logic violations.
UnauthorizedResponse:
content:
application/json:
example:
errors:
- code: '10009'
detail: The required authentication headers were either invalid or not included in the request.
meta:
url: https://developers.telnyx.com/docs/overview/errors/10009
title: Authentication failed
schema:
$ref: '#/components/schemas/call-control_Errors'
description: Unauthorized. Authentication failed - the required authentication headers were either invalid or not included in the request.
parameters:
CallControlId:
description: Unique identifier and token for controlling the call
in: path
name: call_control_id
required: true
schema:
type: string
call-control_PageConsolidated:
description: 'Consolidated page parameter (deepObject style). Originally: page[after], page[before], page[limit], page[size], page[number]'
explode: true
in: query
name: page
schema:
properties:
after:
default: 'null'
description: Opaque identifier of next page
type: string
before:
default: 'null'
description: Opaque identifier of previous page
type: string
limit:
default: 20
description: Limit of records per single page
maximum: 250
minimum: 1
type: integer
number:
default: 1
description: The page number to load
minimum: 1
type: integer
size:
default: 20
description: The size of the page
maximum: 250
minimum: 1
type: integer
type: object
style: deepObject
securitySchemes:
bearerAuth:
scheme: bearer
type: http
branded-calling_bearerAuth:
description: API key passed as a Bearer token in the Authorization header
scheme: bearer
type: http
oauthClientAuth:
description: OAuth 2.0 authentication for Telnyx API and MCP integrations
flows:
authorizationCode:
authorizationUrl: https://api.telnyx.com/v2/oauth/authorize
refreshUrl: https://api.telnyx.com/v2/oauth/token
scopes:
admin: Administrative access to Telnyx resources
tokenUrl: https://api.telnyx.com/v2/oauth/token
clientCredentials:
scopes:
admin: Administrative access to Telnyx resources
tokenUrl: https://api.telnyx.com/v2/oauth/token
type: oauth2
outbound-voice-profiles_bearerAuth:
bearerFormat: JWT
scheme: bearer
type: http
pronunciation-dicts_bearerAuth:
description: Telnyx API v2 key. Obtain from https://portal.telnyx.com
scheme: bearer
type: http
stored-payment-transactions_bearerAuth:
bearerFormat: JWT
scheme: bearer
type: http