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 RCS 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: Send RCS messages
name: RCS
paths:
/messages/rcs:
post:
operationId: SendRCSMessage
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/RCSMessage'
description: RCS message body
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/RCSResponse'
description: Successful operation
4XX:
$ref: '#/components/responses/messaging_GenericErrorResponse'
summary: Send an RCS message
tags:
- RCS
x-latency-category: responsive
/messages/rcs/deeplinks/{agent_id}:
get:
description: Generate a deeplink URL that can be used to start an RCS conversation with a specific agent.
operationId: GenerateRCSDeeplink
parameters:
- description: RCS agent ID
in: path
name: agent_id
required: true
schema:
type: string
- description: Phone number in E164 format (URL encoded)
example: '%2B18445550001'
in: query
name: phone_number
required: false
schema:
type: string
- description: Pre-filled message body (URL encoded)
example: hello%20world
in: query
name: body
required: false
schema:
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/RCSDeeplinkResponse'
description: Successful response with deeplink URL
4XX:
$ref: '#/components/responses/messaging_GenericErrorResponse'
summary: Generate RCS deeplink
tags:
- RCS
x-latency-category: responsive
/messaging/rcs/agents:
get:
operationId: ListRCSAgents
parameters:
- $ref: '#/components/parameters/PageConsolidated'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/RCSAgentsResponse'
description: Successful reponse with the list of RCS agents
4XX:
$ref: '#/components/responses/messaging_GenericErrorResponse'
summary: List all RCS agents
tags:
- RCS
x-latency-category: responsive
/messaging/rcs/agents/{id}:
get:
operationId: GetRCSAgentById
parameters:
- description: RCS agent ID
in: path
name: id
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/RCSAgentResponse'
description: Successful response with the RCS agent
4XX:
$ref: '#/components/responses/messaging_GenericErrorResponse'
summary: Retrieve an RCS agent
tags:
- RCS
x-latency-category: responsive
patch:
operationId: UpdateRCSAgentById
parameters:
- description: RCS agent ID
in: path
name: id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/RCSAgentUpdate'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/RCSAgentResponse'
description: Successful response with the updated RCS agent
4XX:
$ref: '#/components/responses/messaging_GenericErrorResponse'
summary: Modify an RCS agent
tags:
- RCS
x-latency-category: responsive
/messaging/rcs/bulk_capabilities:
post:
operationId: ListRCSCapabilitiesOfAPhoneNumbersBatch
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/RCSCapabilityListRequest'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/RCSCapabilitiesBulk'
description: Successful response
4XX:
$ref: '#/components/responses/messaging_GenericErrorResponse'
summary: Check RCS capabilities (batch)
tags:
- RCS
x-latency-category: responsive
/messaging/rcs/capabilities/{agent_id}/{phone_number}:
get:
operationId: ListRCSCapabilitiesOfAPhoneNumber
parameters:
- description: RCS agent ID
in: path
name: agent_id
required: true
schema:
type: string
- description: Phone number in E164 format
in: path
name: phone_number
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/RCSCapabilitiesSingle'
description: Successful response
4XX:
$ref: '#/components/responses/messaging_GenericErrorResponse'
summary: Check RCS capabilities
tags:
- RCS
x-latency-category: responsive
/messaging/rcs/test_number_invite/{id}/{phone_number}:
put:
description: Adds a test phone number to an RCS agent for testing purposes.
operationId: InviteATestNumberToRCS
parameters:
- description: RCS agent ID
in: path
name: id
required: true
schema:
type: string
- description: Phone number in E164 format to invite for testing
in: path
name: phone_number
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/RCSTestNumberInviteResponse'
description: Test number successfully invited to RCS agent
4XX:
$ref: '#/components/responses/messaging_GenericErrorResponse'
summary: Add RCS test number
tags:
- RCS
x-latency-category: responsive
components:
schemas:
RCSResponse:
properties:
data:
properties:
body:
$ref: '#/components/schemas/RCSAgentMessage'
direction:
example: outbound
type: string
encoding:
example: utf-8
type: string
from:
$ref: '#/components/schemas/RCSFrom'
id:
description: message ID
example: 4031938e-60e4-4235-a8dd-0b1c55a23e7a
type: string
messaging_profile_id:
example: 4001781e-626f-4a41-a914-b1b682150f94
type: string
organization_id:
example: 9f61d8e1-7687-4d6d-9cae-9ff682985983
type: string
received_at:
format: date-time
type: string
record_type:
example: message
type: string
to:
$ref: '#/components/schemas/RCSTo'
type:
example: RCS
type: string
wait_seconds:
description: Seconds the message is queued due to rate limiting before being sent to the carrier. Represents the maximum wait across all applicable rate limits (account, carrier, campaign). 0.0 = no queuing delay.
example: 0.5
format: float
type:
- number
- 'null'
type: object
type: object
RCSMessage:
properties:
agent_id:
description: RCS Agent ID
example: Agent007
type: string
agent_message:
$ref: '#/components/schemas/RCSAgentMessage'
messaging_profile_id:
description: A valid messaging profile ID
type: string
mms_fallback:
$ref: '#/components/schemas/MMSFallback'
sms_fallback:
$ref: '#/components/schemas/SMSFallback'
to:
description: Phone number in +E.164 format
example: '+13125551234'
type: string
type:
description: Message type - must be set to "RCS"
enum:
- RCS
example: RCS
type: string
webhook_url:
description: The URL where webhooks related to this message will be sent.
format: url
type: string
required:
- agent_id
- to
- messaging_profile_id
- agent_message
type: object
RCSAgentMessage:
properties:
content_message:
$ref: '#/components/schemas/RCSContentMessage'
event:
$ref: '#/components/schemas/RCSEvent'
expire_time:
description: Timestamp in UTC of when this message is considered expired
example: '2024-10-02T15:01:23Z'
format: date-time
type: string
ttl:
description: Duration in seconds ending with 's'
example: 10.5s
type: string
type: object
RCSCapabilitiesBulk:
properties:
data:
items:
$ref: '#/components/schemas/RCSCapabilitiesInternal'
type: array
type: object
RCSMedia:
description: A media file within a rich card.
properties:
content_info:
$ref: '#/components/schemas/RCSContentInfo'
height:
description: The height of the media within a rich card with a vertical layout. For a standalone card with horizontal layout, height is not customizable, and this field is ignored.
enum:
- HEIGHT_UNSPECIFIED
- SHORT
- MEDIUM
- TALL
example: MEDIUM
type: string
type: object
RCSTo:
items:
$ref: '#/components/schemas/RCSToItem'
type: array
RCSRichCard:
properties:
carousel_card:
$ref: '#/components/schemas/RCSCarouselCard'
standalone_card:
$ref: '#/components/schemas/RCSStandaloneCard'
type: object
SMSFallback:
properties:
from:
description: Phone number in +E.164 format
example: '+13125551234'
type: string
text:
description: Text (maximum 3072 characters)
example: Hello world!
type: string
type: object
RCSCapabilitiesSingle:
properties:
data:
$ref: '#/components/schemas/RCSCapabilitiesInternal'
type: object
RCSReply:
properties:
postback_data:
description: Payload (base64 encoded) that will be sent to the agent in the user event that results when the user taps the suggested action. Maximum 2048 characters.
type: string
text:
description: Text that is shown in the suggested reply (maximum 25 characters)
type: string
type: object
RCSShareLocationAction:
description: Opens the RCS app's location chooser so the user can pick a location to send back to the agent.
type: object
RCSFrom:
properties:
agent_id:
description: agent ID
example: Agent007
type: string
agent_name:
example: Test Agent
type: string
carrier:
example: Telnyx
type: string
type: object
RCSTestNumberInviteResponse:
properties:
data:
properties:
agent_id:
description: RCS agent ID
example: TestAgent
type: string
phone_number:
description: Phone number that was invited for testing
example: '+13125551234'
type: string
record_type:
description: Identifies the type of the resource
enum:
- rcs.test_number_invite
example: rcs.test_number_invite
type: string
status:
description: Status of the test number invitation
example: PENDING
type: string
type: object
required:
- data
type: object
RCSCarouselCard:
description: Carousel of cards.
properties:
card_contents:
description: The list of contents for each card in the carousel. A carousel can have a minimum of 2 cards and a maximum 10 cards.
items:
$ref: '#/components/schemas/RCSCardContent'
type: array
card_width:
description: The width of the cards in the carousel.
enum:
- CARD_WIDTH_UNSPECIFIED
- SMALL
- MEDIUM
example: SMALL
type: string
required:
- card_width
- card_contents
type: object
MMSFallback:
properties:
from:
description: Phone number in +E.164 format
example: '+13125551234'
type: string
media_urls:
description: List of media URLs
items:
type: string
type: array
subject:
description: Subject of the message
example: Test Message
type: string
text:
description: Text
example: Hello world!
type: string
type: object
RCSAgentResponse:
properties:
data:
$ref: '#/components/schemas/RCSAgent'
type: object
RCSAgentUpdate:
properties:
profile_id:
description: Messaging profile ID associated with the RCS Agent
example: 4001932a-b8a3-42fc-9389-021be6388909
format: uuid
type:
- string
- 'null'
webhook_failover_url:
description: Failover URL to receive RCS events
example: http://example.com
format: url
type:
- string
- 'null'
webhook_url:
description: URL to receive RCS events
example: http://example.com
format: url
type:
- string
- 'null'
type: object
RCSDialAction:
description: Opens the user's default dialer app with the agent-specified phone number filled in.
properties:
phone_number:
description: Phone number in +E.164 format
example: '+13125551234'
type: string
required:
- phone_number
type: object
RCSContentMessage:
properties:
content_info:
$ref: '#/components/schemas/RCSContentInfo'
rich_card:
$ref: '#/components/schemas/RCSRichCard'
suggestions:
description: List of suggested actions and replies
items:
$ref: '#/components/schemas/RCSSuggestion'
type: array
text:
description: Text (maximum 3072 characters)
example: Hello world!
type: string
type: object
RCSCardContent:
properties:
description:
description: Description of the card (at most 2000 characters)
type: string
media:
$ref: '#/components/schemas/RCSMedia'
suggestions:
description: List of suggestions to include in the card. Maximum 10 suggestions.
items:
$ref: '#/components/schemas/RCSSuggestion'
type: array
title:
description: Title of the card (at most 200 characters)
example: Elephant
type: string
type: object
RCSEvent:
description: RCS Event to send to the recipient
properties:
event_type:
enum:
- TYPE_UNSPECIFIED
- IS_TYPING
- READ
example: IS_TYPING
type: string
type: object
RCSContentInfo:
properties:
file_url:
description: Publicly reachable URL of the file.
example: https://example.com/elephant.jpg
format: url
type: string
force_refresh:
description: If set the URL content will not be cached.
type: boolean
thumbnail_url:
description: Publicly reachable URL of the thumbnail. Maximum size of 100 kB.
format: url
type: string
required:
- file_url
type: object
RCSToItem:
properties:
carrier:
example: Verizon Wireless
type: string
line_type:
example: Wireless
type: string
phone_number:
example: '+13125551234'
type: string
status:
example: queued
type: string
type: object
RCSOpenUrlAction:
description: Opens the user's default web browser app to the specified URL.
properties:
application:
description: URL open application, browser or webview.
enum:
- OPEN_URL_APPLICATION_UNSPECIFIED
- BROWSER
- WEBVIEW
example: BROWSER
type: string
description:
description: Accessbility description for webview.
type: string
url:
example: http://example.com
format: url
type: string
webview_view_mode:
enum:
- WEBVIEW_VIEW_MODE_UNSPECIFIED
- FULL
- HALF
- TALL
example: HALF
type: string
required:
- url
- application
- webview_view_mode
type: object
RCSAgentsResponse:
properties:
data:
items:
$ref: '#/components/schemas/RCSAgent'
type: array
meta:
$ref: '#/components/schemas/messaging_PaginationMeta'
type: object
RCSAgent:
properties:
agent_id:
description: RCS Agent ID
example: TestAgent
type: string
agent_name:
description: Human readable agent name
example: Test Agent
type: string
created_at:
description: Date and time when the resource was created
example: '2024-01-01T12:00:00.000Z'
format: date-time
type: string
enabled:
description: Specifies whether the agent is enabled
example: true
type: boolean
profile_id:
description: Messaging profile ID associated with the RCS Agent
example: 4001932a-b8a3-42fc-9389-021be6388909
format: uuid
type:
- string
- 'null'
updated_at:
description: Date and time when the resource was updated
example: '2024-01-01T12:00:00.000Z'
format: date-time
type: string
user_id:
description: User ID associated with the RCS Agent
example: 2ecf295b-36c6-4d43-ad05-71eb1e560518
type: string
webhook_failover_url:
description: Failover URL to receive RCS events
example: http://example.com
format: url
type:
- string
- 'null'
webhook_url:
description: URL to receive RCS events
example: http://example.com
format: url
type:
- string
- 'null'
type: object
RCSCreateCalendarEventAction:
description: Opens the user's default calendar app and starts the new calendar event flow with the agent-specified event data pre-filled.
properties:
description:
description: Event description. Maximum 500 characters.
type: string
end_time:
example: '2024-10-02T15:02:31Z'
format: date-time
type: string
start_time:
example: '2024-10-02T15:01:23Z'
format: date-time
type: string
title:
description: Event title. Maximum 100 characters.
type: string
type: object
RCSLatLng:
properties:
latitude:
description: The latitude in degrees. It must be in the range [-90.0, +90.0].
example: 41.8
type: number
longitude:
description: The longitude in degrees. It must be in the range [-180.0, +180.0].
example: -87.6
type: number
required:
- latitude
- longitude
type: object
RCSAction:
description: When tapped, initiates the corresponding native action on the device.
properties:
create_calendar_event_action:
$ref: '#/components/schemas/RCSCreateCalendarEventAction'
dial_action:
$ref: '#/components/schemas/RCSDialAction'
fallback_url:
description: Fallback URL to use if a client doesn't support a suggested action. Fallback URLs open in new browser windows. Maximum 2048 characters.
format: url
type: string
open_url_action:
$ref: '#/components/schemas/RCSOpenUrlAction'
postback_data:
description: Payload (base64 encoded) that will be sent to the agent in the user event that results when the user taps the suggested action. Maximum 2048 characters.
type: string
share_location_action:
$ref: '#/components/schemas/RCSShareLocationAction'
text:
description: Text that is shown in the suggested action. Maximum 25 characters.
example: Hello world
type: string
view_location_action:
$ref: '#/components/schemas/RCSViewLocationAction'
type: object
RCSCapabilitiesInternal:
properties:
agent_id:
description: RCS agent ID
example: TestAgent
type: string
agent_name:
description: RCS agent name
example: Testing agent
type: string
features:
description: List of RCS capabilities
items:
type: string
type: array
phone_number:
description: Phone number
example: '+13125551234'
type: string
record_type:
description: Identifies the type of the resource
enum:
- rcs.capabilities
example: rcs.capabilities
type: string
type: object
RCSViewLocationAction:
description: Opens the user's default map app and selects the agent-specified location.
properties:
label:
description: The label of the pin dropped
type: string
lat_long:
$ref: '#/components/schemas/RCSLatLng'
query:
description: query string (Android only)
type: string
type: object
RCSStandaloneCard:
description: Standalone card
properties:
card_content:
$ref: '#/components/schemas/RCSCardContent'
card_orientation:
description: Orientation of the card.
enum:
- CARD_ORIENTATION_UNSPECIFIED
- HORIZONTAL
- VERTICAL
example: HORIZONTAL
type: string
thumbnail_image_alignment:
description: Image preview alignment for standalone cards with horizontal layout.
enum:
- THUMBNAIL_IMAGE_ALIGNMENT_UNSPECIFIED
- LEFT
- RIGHT
example: LEFT
type: string
required:
- card_orientation
- thumbnail_image_alignment
- card_content
type: object
messaging_Errors:
properties:
errors:
items:
$ref: '#/components/schemas/messaging_Error'
type: array
RCSDeeplinkResponse:
properties:
data:
properties:
url:
description: The generated deeplink URL
example: sms:+18445550001?service_id=my_agent_id%40rbm.goog&body=hello%20world
type: string
required:
- url
type: object
required:
- data
type: object
RCSSuggestion:
properties:
action:
$ref: '#/components/schemas/RCSAction'
reply:
$ref: '#/components/schemas/RCSReply'
type: object
messaging_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
required:
- total_pages
- total_results
- page_size
- page_number
type: object
messaging_Error:
properties:
code:
type: string
x-format: integer
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
RCSCapabilityListRequest:
properties:
agent_id:
description: RCS Agent ID
example: TestAgent
type: string
phone_numbers:
description: List of phone numbers to check
items:
example: '+13125551234'
type: string
type: array
required:
- agent_id
- phone_numbers
type: object
responses:
messaging_GenericErrorResponse:
content:
application/json:
schema:
$ref: '#/components/schemas/messaging_Errors'
description: Unexpected error
parameters:
PageConsolidated:
description: 'Consolidated page parameter (deepObject style). Originally: page[number], page[size]'
explode: true
in: query
name: page
schema:
properties:
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