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 Call Information 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: Call information
name: Call Information
paths:
/calls/{call_control_id}:
get:
description: Returns the status of a call (data is available 10 minutes after call ended).
operationId: RetrieveCallStatus
parameters:
- $ref: '#/components/parameters/CallControlId'
responses:
'200':
$ref: '#/components/responses/RetrieveCallStatusResponse'
'422':
$ref: '#/components/responses/UnprocessableEntityResponse'
default:
$ref: '#/components/responses/call-control_GenericErrorResponse'
summary: Retrieve a call status
tags:
- Call Information
x-latency-category: interactive
/connections/{connection_id}/active_calls:
get:
description: 'Lists all active calls for given connection. Acceptable connections are either SIP connections with webhook_url or xml_request_url, call control or texml. Returned results are cursor paginated.
'
operationId: ListConnectionActiveCalls
parameters:
- $ref: '#/components/parameters/ConnectionId'
- $ref: '#/components/parameters/call-control_PageConsolidated'
responses:
'200':
$ref: '#/components/responses/ActiveCallsResponse'
'422':
$ref: '#/components/responses/UnprocessableEntityResponse'
default:
$ref: '#/components/responses/call-control_GenericErrorResponse'
summary: List all active calls for given connection
tags:
- Call Information
x-group-parameters: 'true'
x-latency-category: responsive
components:
schemas:
ActiveCall:
example:
call_control_id: v3:MdI91X4lWFEs7IgbBEOT9M4AigoY08M0WWZFISt1Yw2axZ_IiE4pqg
call_duration: 50
call_leg_id: 2dc6fc34-f9e0-11ea-b68e-02420a0f7768
call_session_id: 2dc1b3c8-f9e0-11ea-bc5a-02420a0f7768
client_state: aGF2ZSBhIG5pY2UgZGF5ID1d
record_type: call
properties:
call_control_id:
description: Unique identifier and token for controlling the call.
example: v3:MdI91X4lWFEs7IgbBEOT9M4AigoY08M0WWZFISt1Yw2axZ_IiE4pqg
type: string
call_duration:
description: Indicates the duration of the call in seconds
example: 50
type: integer
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
client_state:
description: State received from a command.
example: aGF2ZSBhIG5pY2UgZGF5ID1d
type: string
record_type:
enum:
- call
example: call
type: string
required:
- call_control_id
- call_leg_id
- call_session_id
- client_state
- record_type
- call_duration
title: Active Call
type: object
CursorPaginationMeta:
properties:
cursors:
$ref: '#/components/schemas/Cursor'
next:
description: Path to next page.
example: /v2/connections/1234567890/active_calls?page[after]=v1:g3QAAAADZAAKdGVsbnl4X2lkc2wAAAABbQAAACRlYmRiYzdkNi1kZWRmLTExZWQtYTM3MS0wMjQyMGFlZjAwYjRqZAAJdGltZXN0YW1wbggA8Le4pGhpVxdkAAR0eXBlZAAFYWZ0ZXI=
type: string
previous:
description: Path to previous page.
example: /v2/connections/1234567890/active_calls?page[before]=v1:g3QAAAADZAAKdGVsbnl4X2lkc2wAAAABbQAAACRlYmRiYzdkNi1kZWRmLTExZWQtYTM3MS0wMjQyMGFlZjAwYjRqZAAJdGltZXN0YW1wbggA8Le4pGhpVxdkAAR0eXBlZAAFYWZ0ZXI=
type: string
total_items:
example: 50
type: integer
title: Cursor Pagination Meta
type: object
Call:
example:
call_control_id: v3:MdI91X4lWFEs7IgbBEOT9M4AigoY08M0WWZFISt1Yw2axZ_IiE4pqg
call_duration: 50
call_leg_id: 2dc6fc34-f9e0-11ea-b68e-02420a0f7768
call_session_id: 2dc1b3c8-f9e0-11ea-bc5a-02420a0f7768
client_state: aGF2ZSBhIG5pY2UgZGF5ID1d
end_time: '2019-01-23T18:11:52.574Z'
is_alive: false
record_type: call
start_time: '2019-01-23T18:10:02.574Z'
properties:
call_control_id:
description: Unique identifier and token for controlling the call.
example: v3:MdI91X4lWFEs7IgbBEOT9M4AigoY08M0WWZFISt1Yw2axZ_IiE4pqg
type: string
call_duration:
description: Indicates the duration of the call in seconds
example: 50
type: integer
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
client_state:
description: State received from a command.
example: aGF2ZSBhIG5pY2UgZGF5ID1d
type: string
end_time:
description: ISO 8601 formatted date indicating when the call ended. Only present when the call is not alive
example: '2019-01-23T18:11:52.574Z'
type: string
is_alive:
description: Indicates whether the call is alive or not. For Dial command it will always be `false` (dialing is asynchronous).
example: true
type: boolean
record_type:
enum:
- call
example: call
type: string
start_time:
description: ISO 8601 formatted date indicating when the call started
example: '2019-01-23T18:10:02.574Z'
type: string
required:
- call_control_id
- call_leg_id
- call_session_id
- is_alive
- record_type
title: Call
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
Cursor:
properties:
after:
description: Opaque identifier of next page.
example: v1:g3QAAAADZAAKdGVsbnl4X2lkc2wAAAABbQAAACRlYmRiYzdkNi1kZWRmLTExZWQtYTM3MS0wMjQyMGFlZjAwYjRqZAAJdGltZXN0YW1wbggA8Le4pGhpVxdkAAR0eXBlZAAFYWZ0ZXI=
type: string
before:
description: Opaque identifier of previous page.
example: v1:g3QAAAADZAAKdGVsbnl4X2lkc2wAAAABbQAAACRlYmRiYzdkNi1kZWRmLTExZWQtYTM3MS0wMjQyMGFlZjAwYjRqZAAJdGltZXN0YW1wbggA8Le4pGhpVxdkAAR0eXBlZAAFYWZ0ZXI=
type: string
type: object
call-control_Errors:
properties:
errors:
items:
$ref: '#/components/schemas/call-control_Error'
type: array
parameters:
ConnectionId:
description: Telnyx connection id
in: path
name: connection_id
required: true
schema:
example: '1293384261075731461'
type: string
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
responses:
RetrieveCallStatusResponse:
content:
application/json:
schema:
properties:
data:
$ref: '#/components/schemas/Call'
title: Retrieve Call Status Response
type: object
description: Successful response with details about a call status.
call-control_GenericErrorResponse:
content:
application/json:
schema:
$ref: '#/components/schemas/call-control_Errors'
description: Unexpected error
ActiveCallsResponse:
content:
application/json:
schema:
properties:
data:
items:
$ref: '#/components/schemas/ActiveCall'
type: array
meta:
$ref: '#/components/schemas/CursorPaginationMeta'
title: Active Calls Response
type: object
description: Successful response with list of details about active calls.
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.
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