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 Messages 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: Messages
name: Messages
paths:
/messages:
post:
description: 'Send a message with a Phone Number, Alphanumeric Sender ID, Short Code or Number Pool.
This endpoint allows you to send a message with any messaging resource.
Current messaging resources include: long-code, short-code, number-pool, and
alphanumeric-sender-id.
'
operationId: SendMessage
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateMessageRequest'
description: Message payload
responses:
'200':
$ref: '#/components/responses/MessageResponse'
4XX:
$ref: '#/components/responses/messaging_GenericErrorResponse'
summary: Send a message
tags:
- Messages
x-latency-category: responsive
/messages/alphanumeric_sender_id:
post:
description: Send an SMS message using an alphanumeric sender ID. This is SMS only.
operationId: SendAlphanumericSenderIdMessage
requestBody:
content:
application/json:
schema:
properties:
from:
description: A valid alphanumeric sender ID on the user's account.
example: MyCompany
type: string
messaging_profile_id:
description: The messaging profile ID to use.
format: uuid
type: string
text:
description: The message body.
type: string
to:
$ref: '#/components/schemas/ToNumber'
description: Receiving address (+E.164 formatted phone number).
use_profile_webhooks:
description: If true, use the messaging profile's webhook settings.
type: boolean
webhook_failover_url:
description: Failover callback URL for delivery status updates.
format: url
type:
- string
- 'null'
webhook_url:
description: Callback URL for delivery status updates.
format: url
type:
- string
- 'null'
required:
- from
- to
- text
- messaging_profile_id
type: object
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/OutboundMessageResponse'
description: Successful response with the sent message.
'400':
$ref: '#/components/responses/messaging_BadRequestResponse'
'401':
$ref: '#/components/responses/messaging_UnauthorizedResponse'
'422':
$ref: '#/components/responses/messaging_UnprocessableEntityResponse'
summary: Send a message using an alphanumeric sender ID
tags:
- Messages
x-latency-category: responsive
/messages/group/{message_id}:
get:
description: Retrieve all messages in a group MMS conversation by the group message ID.
operationId: GetGroupMmsMessages
parameters:
- description: The group message ID.
in: path
name: message_id
required: true
schema:
format: uuid
type: string
responses:
'200':
content:
application/json:
schema:
properties:
data:
items:
$ref: '#/components/schemas/OutboundMessagePayload'
type: array
type: object
description: Successful response with group MMS messages.
'401':
$ref: '#/components/responses/messaging_UnauthorizedResponse'
'404':
$ref: '#/components/responses/messaging_NotFoundResponse'
summary: Retrieve group MMS messages
tags:
- Messages
x-latency-category: responsive
/messages/group_mms:
post:
operationId: CreateGroupMmsMessage
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateGroupMMSMessageRequest'
description: Message payload
responses:
'200':
$ref: '#/components/responses/MessageResponse'
4XX:
$ref: '#/components/responses/messaging_GenericErrorResponse'
summary: Send a group MMS message
tags:
- Messages
x-latency-category: responsive
/messages/long_code:
post:
operationId: CreateLongCodeMessage
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateLongCodeMessageRequest'
description: Message payload
responses:
'200':
$ref: '#/components/responses/MessageResponse'
4XX:
$ref: '#/components/responses/messaging_GenericErrorResponse'
summary: Send a long code message
tags:
- Messages
x-latency-category: responsive
/messages/number_pool:
post:
operationId: CreateNumberPoolMessage
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateNumberPoolMessageRequest'
description: Message payload
responses:
'200':
$ref: '#/components/responses/MessageResponse'
4XX:
$ref: '#/components/responses/messaging_GenericErrorResponse'
summary: Send a message using number pool
tags:
- Messages
x-latency-category: responsive
/messages/schedule:
post:
description: 'Schedule a message with a Phone Number, Alphanumeric Sender ID, Short Code or Number Pool.
This endpoint allows you to schedule a message with any messaging resource.
Current messaging resources include: long-code, short-code, number-pool, and
alphanumeric-sender-id.
'
operationId: ScheduleMessage
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateScheduledMessageRequest'
description: Message payload with send_at set
responses:
'200':
$ref: '#/components/responses/MessageResponse'
4XX:
$ref: '#/components/responses/messaging_GenericErrorResponse'
summary: Schedule a message
tags:
- Messages
x-latency-category: responsive
/messages/short_code:
post:
operationId: CreateShortCodeMessage
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateShortCodeMessageRequest'
description: Message payload
responses:
'200':
$ref: '#/components/responses/MessageResponse'
4XX:
$ref: '#/components/responses/messaging_GenericErrorResponse'
summary: Send a short code message
tags:
- Messages
x-latency-category: responsive
/messages/{id}:
delete:
description: Cancel a scheduled message that has not yet been sent. Only messages with `status=scheduled` and `send_at` more than a minute from now can be cancelled.
operationId: CancelMessage
parameters:
- description: The id of the message to cancel
in: path
name: id
required: true
schema:
format: uuid
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/OutboundMessagePayloadCancelled'
description: Successful response
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/messaging_Error'
description: Forbidden
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/messaging_Error'
description: Not found.
4XX:
$ref: '#/components/responses/messaging_GenericErrorResponse'
summary: Cancel a scheduled message
tags:
- Messages
x-latency-category: responsive
get:
description: 'Note: This API endpoint can only retrieve messages that are no older than 10 days since their creation. If you require messages older than this, please generate an [MDR report.](https://developers.telnyx.com/api-reference/mdr-usage-reports/create-mdr-usage-report)'
operationId: GetMessage
parameters:
- description: The id of the message
in: path
name: id
required: true
schema:
format: uuid
type: string
responses:
'200':
content:
application/json:
schema:
properties:
data:
oneOf:
- $ref: '#/components/schemas/OutboundMessagePayload'
- $ref: '#/components/schemas/InboundMessagePayload'
type: object
description: Successful response with details of a message.
4XX:
$ref: '#/components/responses/messaging_GenericErrorResponse'
summary: Retrieve a message
tags:
- Messages
x-latency-category: responsive
components:
schemas:
OutboundMessagePayload:
example:
cc: []
completed_at: null
cost:
amount: '0.0051'
currency: USD
cost_breakdown:
carrier_fee:
amount: '0.00305'
currency: USD
rate:
amount: '0.00205'
currency: USD
direction: outbound
encoding: GSM-7
errors: []
from:
carrier: TELNYX LLC
line_type: VoIP
phone_number: '+18445550001'
id: 40385f64-5717-4562-b3fc-2c963f66afa6
media:
- content_type: null
sha256: null
size: null
url: https://pbs.twimg.com/profile_images/1142168442042118144/AW3F4fFD_400x400.png
messaging_profile_id: 4000eba1-a0c0-4563-9925-b25e842a7cb6
organization_id: b448f9cc-a842-4784-98e9-03c1a5872950
parts: 1
received_at: '2019-01-23T18:10:02.574Z'
record_type: message
sent_at: null
subject: From Telnyx!
tags:
- Greetings
tcr_campaign_billable: true
tcr_campaign_id: TCPA3X7
tcr_campaign_registered: REGISTERED
text: Hello, World!
to:
- carrier: T-MOBILE USA, INC.
line_type: Wireless
phone_number: '+18665550001'
status: queued
type: MMS
valid_until: null
wait_seconds: 0.5
webhook_failover_url: https://backup.example.com/hooks
webhook_url: https://www.example.com/hooks
properties:
cc:
items:
properties:
carrier:
description: The carrier of the receiver.
type: string
line_type:
description: The line-type of the receiver.
enum:
- Wireline
- Wireless
- VoWiFi
- VoIP
- Pre-Paid Wireless
- ''
type: string
phone_number:
description: Receiving address (+E.164 formatted phone number or short code).
type: string
x-format: address
status:
enum:
- queued
- sending
- sent
- delivered
- sending_failed
- delivery_failed
- delivery_unconfirmed
type: string
type: object
type: array
completed_at:
description: ISO 8601 formatted date indicating when the message was finalized.
format: date-time
type:
- string
- 'null'
cost:
properties:
amount:
description: The amount deducted from your account.
type: string
x-format: decimal
currency:
description: The ISO 4217 currency identifier.
type: string
x-format: iso4217
type:
- object
- 'null'
cost_breakdown:
description: Detailed breakdown of the message cost components.
properties:
carrier_fee:
properties:
amount:
description: The carrier fee amount.
type: string
x-format: decimal
currency:
description: The ISO 4217 currency identifier.
type: string
x-format: iso4217
type: object
rate:
properties:
amount:
description: The rate amount applied.
type: string
x-format: decimal
currency:
description: The ISO 4217 currency identifier.
type: string
x-format: iso4217
type: object
type:
- object
- 'null'
direction:
description: The direction of the message. Inbound messages are sent to you whereas outbound messages are sent from you.
enum:
- outbound
example: outbound
type: string
encoding:
description: Encoding scheme used for the message body.
type: string
errors:
description: These errors may point at addressees when referring to unsuccessful/unconfirmed delivery statuses.
items:
$ref: '#/components/schemas/messaging_Error'
type: array
from:
properties:
carrier:
description: The carrier of the receiver.
type: string
line_type:
description: The line-type of the receiver.
enum:
- Wireline
- Wireless
- VoWiFi
- VoIP
- Pre-Paid Wireless
- ''
type: string
phone_number:
description: Sending address (+E.164 formatted phone number, alphanumeric sender ID, or short code).
type: string
x-format: address
type: object
id:
description: Identifies the type of resource.
format: uuid
type: string
media:
items:
properties:
content_type:
description: The MIME type of the requested media.
type:
- string
- 'null'
x-format: mime-type
sha256:
description: The SHA256 hash of the requested media.
type:
- string
- 'null'
size:
description: The size of the requested media.
type:
- integer
- 'null'
url:
description: The url of the media requested to be sent.
format: url
type: string
type: object
type: array
messaging_profile_id:
description: Unique identifier for a messaging profile.
type: string
organization_id:
description: The id of the organization the messaging profile belongs to.
format: uuid
type: string
parts:
description: Number of parts into which the message's body must be split.
maximum: 10
minimum: 1
type: integer
received_at:
description: ISO 8601 formatted date indicating when the message request was received.
format: date-time
type: string
record_type:
description: Identifies the type of the resource.
enum:
- message
example: message
type: string
sent_at:
description: ISO 8601 formatted date indicating when the message was sent.
format: date-time
type:
- string
- 'null'
smart_encoding_applied:
description: Indicates whether smart encoding was applied to this message. When `true`, one or more Unicode characters were automatically replaced with GSM-7 equivalents to reduce segment count and cost. The original message text is preserved in webhooks.
type: boolean
subject:
description: Subject of multimedia message
type:
- string
- 'null'
tags:
description: Tags associated with the resource.
items:
type: string
type: array
tcr_campaign_billable:
description: Indicates whether the TCR campaign is billable.
type: boolean
tcr_campaign_id:
description: The Campaign Registry (TCR) campaign ID associated with the message.
type:
- string
- 'null'
tcr_campaign_registered:
description: The registration status of the TCR campaign.
example: REGISTERED
type:
- string
- 'null'
text:
description: 'Message body (i.e., content) as a non-empty string.
**Required for SMS**'
type: string
to:
items:
properties:
carrier:
description: The carrier of the receiver.
type: string
line_type:
description: The line-type of the receiver.
enum:
- Wireline
- Wireless
- VoWiFi
- VoIP
- Pre-Paid Wireless
- ''
type: string
phone_number:
description: Receiving address (+E.164 formatted phone number or short code).
type: string
x-format: address
status:
description: The delivery status of the message.
enum:
- queued
- sending
- sent
- expired
- sending_failed
- delivery_unconfirmed
- delivered
- delivery_failed
type: string
type: object
type: array
type:
description: The type of message.
enum:
- SMS
- MMS
type: string
valid_until:
description: Message must be out of the queue by this time or else it will be discarded and marked as 'sending_failed'. Once the message moves out of the queue, this field will be nulled
format: date-time
type:
- string
- 'null'
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'
webhook_failover_url:
description: The failover URL where webhooks related to this message will be sent if sending to the primary URL fails.
format: url
type:
- string
- 'null'
webhook_url:
description: The URL where webhooks related to this message will be sent.
format: url
type:
- string
- 'null'
type: object
CreateShortCodeMessageRequest:
example:
from: '+18445550001'
media_urls:
- http://example.com
subject: From Telnyx!
text: Hello, World!
to: '+18445550001'
type: MMS
use_profile_webhooks: true
webhook_failover_url: https://backup.example.com/hooks
webhook_url: http://example.com/webhooks
properties:
auto_detect:
default: false
description: Automatically detect if an SMS message is unusually long and exceeds a recommended limit of message parts.
type: boolean
encoding:
default: auto
description: Encoding to use for the message. `auto` (default) uses smart encoding to automatically select the most efficient encoding. `gsm7` forces GSM-7 encoding (returns 400 if message contains characters that cannot be encoded). `ucs2` forces UCS-2 encoding and disables smart encoding. When set, this overrides the messaging profile's `smart_encoding` setting.
enum:
- auto
- gsm7
- ucs2
type: string
from:
description: Phone number, in +E.164 format, used to send the message.
type: string
x-format: address
media_urls:
description: 'A list of media URLs. The total media size must be less than 1 MB.
**Required for MMS**'
items:
format: url
type: string
type: array
subject:
description: Subject of multimedia message
type: string
text:
description: 'Message body (i.e., content) as a non-empty string.
**Required for SMS**'
type: string
to:
$ref: '#/components/schemas/ToNumber'
type:
description: The protocol for sending the message, either SMS or MMS.
enum:
- SMS
- MMS
type: string
use_profile_webhooks:
default: true
description: If the profile this number is associated with has webhooks, use them for delivery notifications. If webhooks are also specified on the message itself, they will be attempted first, then those on the profile.
type: boolean
webhook_failover_url:
description: The failover URL where webhooks related to this message will be sent if sending to the primary URL fails.
format: url
type: string
webhook_url:
description: The URL where webhooks related to this message will be sent.
format: url
type: string
required:
- from
- to
type: object
OutboundMessagePayloadCancelled:
example:
cc: []
completed_at: null
cost:
amount: '0.0'
currency: USD
cost_breakdown: null
direction: outbound
encoding: GSM-7
errors: []
from:
carrier: TELNYX LLC
line_type: VoIP
phone_number: '+18445550001'
id: 40385f64-5717-4562-b3fc-2c963f66afa6
media: []
messaging_profile_id: 4000eba1-a0c0-4563-9925-b25e842a7cb6
organization_id: b448f9cc-a842-4784-98e9-03c1a5872950
parts: 1
received_at: '2019-01-23T18:10:02.574Z'
record_type: message
sent_at: null
subject: From Telnyx!
tags:
- Greetings
tcr_campaign_billable: true
tcr_campaign_id: TCPA3X7
tcr_campaign_registered: REGISTERED
text: Hello, World!
to:
- carrier: T-MOBILE USA, INC.
line_type: Wireless
phone_number: '+18665550001'
status: cancelled
type: SMS
valid_until: null
webhook_failover_url: https://backup.example.com/hooks
webhook_url: https://www.example.com/hooks
properties:
cc:
items:
properties:
carrier:
description: The carrier of the receiver.
type: string
line_type:
description: The line-type of the receiver.
enum:
- Wireline
- Wireless
- VoWiFi
- VoIP
- Pre-Paid Wireless
- ''
type: string
phone_number:
description: Receiving address (+E.164 formatted phone number or short code).
type: string
x-format: address
status:
description: The delivery status of the message.
enum:
- scheduled
- queued
- sending
- sent
- cancelled
- expired
- sending_failed
- delivery_unconfirmed
- delivered
- delivery_failed
type: string
type: object
type: array
completed_at:
description: ISO 8601 formatted date indicating when the message was finalized.
format: date-time
type:
- string
- 'null'
cost:
properties:
amount:
description: The amount deducted from your account.
type: string
x-format: decimal
currency:
description: The ISO 4217 currency identifier.
type: string
x-format: iso4217
type:
- object
- 'null'
cost_breakdown:
description: Detailed breakdown of the message cost components.
properties:
carrier_fee:
properties:
amount:
description: The carrier fee amount.
type: string
x-format: decimal
currency:
description: The ISO 4217 currency identifier.
type: string
x-format: iso4217
type: object
rate:
properties:
amount:
description: The rate amount applied.
type: string
x-format: decimal
currency:
description: The ISO 4217 currency identifier.
type: string
x-format: iso4217
type: object
type:
- object
- 'null'
direction:
description: The direction of the message. Inbound messages are sent to you whereas outbound messages are sent from you.
enum:
- outbound
example: outbound
type: string
encoding:
description: Encoding scheme used for the message body.
type: string
errors:
description: These errors may point at addressees when referring to unsuccessful/unconfirmed delivery statuses.
items:
$ref: '#/components/schemas/messaging_Error'
type: array
from:
properties:
carrier:
description: The carrier of the receiver.
type: string
line_type:
description: The line-type of the receiver.
enum:
- Wireline
- Wireless
- VoWiFi
- VoIP
- Pre-Paid Wireless
- ''
type: string
phone_number:
description: Sending address (+E.164 formatted phone number, alphanumeric sender ID, or short code).
type: string
x-format: address
type: object
id:
description: Identifies the type of resource.
format: uuid
type: string
media:
items:
properties:
content_type:
description: The MIME type of the requested media.
type:
- string
- 'null'
x-format: mime-type
sha256:
description: The SHA256 hash of the requested media.
type:
- string
- 'null'
size:
description: The size of the requested media.
type:
- integer
- 'null'
url:
description: The url of the media requested to be sent.
format: url
type: string
type: object
type: array
messaging_profile_id:
description: Unique identifier for a messaging profile.
type: string
organization_id:
description: The id of the organization the messaging profile belongs to.
format: uuid
type: string
parts:
description: Number of parts into which the message's body must be split.
maximum: 10
minimum: 1
type: integer
received_at:
description: ISO 8601 formatted date indicating when the message request was received.
format: date-time
type: string
record_type:
description: Identifies the type of the resource.
enum:
- message
example: message
type: string
sent_at:
description: ISO 8601 formatted date indicating when the message was sent.
format: date-time
type:
- string
- 'null'
smart_encoding_applied:
description: Indicates whether smart encoding was applied to this message. When `true`, one or more Unicode characters were automatically replaced with GSM-7 equivalents to reduce segment count and cost. The original message text is preserved in webhooks.
type: boolean
subject:
description: Subject of multimedia message
type:
- string
- 'null'
tags:
description: Tags associated with the resource.
items:
type: string
type: array
tcr_campaign_billable:
description: Indicates whether the TCR campaign is billable.
type: boolean
tcr_campaign_id:
description: The Campaign Registry (TCR) campaign ID associated with the message.
type:
- string
- 'null'
tcr_campaign_registered:
description: The registration status of the TCR campaign.
example: REGISTERED
type:
- string
- 'null'
text:
description: 'Message body (i.e., content) as a non-empty string.
**Required for SMS**'
type: string
to:
items:
properties:
carrier:
description: The carrier of the receiver.
type: string
line_type:
description: The line-type of the receiver.
enum:
- Wireline
- Wireless
- VoWiFi
- VoIP
- Pre-Paid Wireless
- ''
type: string
phone_number:
description: Receiving address (+E.164 formatted phone number or short code).
type: string
x-format: address
status:
description: The delivery status of the message.
enum:
- scheduled
- queued
- sending
- sent
- cancelled
- expired
- sending_failed
- delivery_unconfirmed
- delivered
- delivery_failed
ty
# --- truncated at 32 KB (58 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/telnyx/refs/heads/main/openapi/telnyx-messages-api-openapi.yml