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 Whatsapp messaging 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 Whatsapp messages
name: Whatsapp messaging
paths:
/messages/whatsapp:
post:
operationId: SendWhatsappMessage
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/WhatsappMessage'
description: Whatsapp message body
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/WhatsappResponse'
description: Successful operation
4XX:
$ref: '#/components/responses/messaging_GenericErrorResponse'
summary: Send a Whatsapp message
tags:
- Whatsapp messaging
x-hidden: true
x-latency-category: responsive
components:
schemas:
WhatsappResponse:
properties:
data:
properties:
body:
$ref: '#/components/schemas/WhatsappMessageContent'
direction:
example: outbound
type: string
encoding:
example: utf-8
type: string
from:
properties:
carrier:
description: The carrier of the sender.
type: string
line_type:
description: The line-type of the sender.
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
status:
enum:
- received
- delivered
type: string
type: object
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: WHATSAPP
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
WhatsappReaction:
properties:
emoji:
type: string
message_id:
type: string
type: object
WhatsappMedia:
properties:
caption:
description: media caption
type: string
filename:
description: file name with extension
type: string
link:
description: media URL
example: http://example.com/media.jpg
format: url
type: string
voice:
description: true if voice message
type: boolean
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
messaging_Errors:
properties:
errors:
items:
$ref: '#/components/schemas/messaging_Error'
type: array
WhatsappMessage:
properties:
from:
description: Phone number in +E.164 format associated with Whatsapp account
example: '+13125551234'
type: string
messaging_profile_id:
description: Messaging profile ID - required if the 'from' number is not SMS-enabled
format: uuid
type: string
to:
description: Phone number in +E.164 format
example: '+13125551234'
type: string
type:
description: Message type - must be set to "WHATSAPP"
enum:
- WHATSAPP
example: WHATSAPP
type: string
webhook_url:
description: The URL where webhooks related to this message will be sent.
format: url
type: string
whatsapp_message:
$ref: '#/components/schemas/WhatsappMessageContent'
required:
- from
- to
- whatsapp_message
type: object
WhatsappInteractive:
properties:
action:
properties:
button:
type: string
buttons:
items:
properties:
reply:
properties:
id:
description: unique identifier for each button, 256 character maximum
type: string
title:
description: button label, 20 character maximum
type: string
type: object
type:
enum:
- reply
type: string
type: object
type: array
cards:
items:
properties:
action:
properties:
catalog_id:
description: the unique ID of the catalog
type: string
product_retailer_id:
description: the unique retailer ID of the product
type: string
type: object
body:
properties:
text:
description: 160 character maximum, up to 2 line breaks
type: string
type: object
card_index:
description: unique index for each card (0-9)
type: integer
header:
properties:
image:
$ref: '#/components/schemas/WhatsappMedia'
type:
enum:
- image
- video
type: string
video:
$ref: '#/components/schemas/WhatsappMedia'
type: object
type:
enum:
- cta_url
type: string
type: object
type: array
catalog_id:
type: string
mode:
type: string
name:
type: string
parameters:
properties:
display_text:
description: button label text, 20 character maximum
type: string
url:
description: button URL to load when tapped by the user
format: url
type: string
type: object
product_retailer_id:
type: string
sections:
items:
properties:
product_items:
items:
properties:
product_retailer_id:
type: string
type: object
type: array
rows:
items:
properties:
description:
description: row description, 72 character maximum
type: string
id:
description: arbitrary string identifying the row, 200 character maximum
type: string
title:
description: row title, 24 character maximum
type: string
type: object
type: array
title:
description: section title, 24 character maximum
type: string
type: object
type: array
type: object
body:
properties:
text:
description: body text, 1024 character maximum
type: string
type: object
footer:
properties:
text:
description: footer text, 60 character maximum
type: string
type: object
header:
properties:
document:
$ref: '#/components/schemas/WhatsappMedia'
image:
$ref: '#/components/schemas/WhatsappMedia'
sub_text:
type: string
text:
description: header text, 60 character maximum
type: string
video:
$ref: '#/components/schemas/WhatsappMedia'
type: object
type:
enum:
- cta_url
- list
- carousel
- button
- location_request_message
type: string
type: object
WhatsappMessageContent:
properties:
audio:
$ref: '#/components/schemas/WhatsappMedia'
biz_opaque_callback_data:
description: custom data to return with status update
type: string
contacts:
items:
$ref: '#/components/schemas/WhatsappContact'
type: array
document:
$ref: '#/components/schemas/WhatsappMedia'
image:
$ref: '#/components/schemas/WhatsappMedia'
interactive:
$ref: '#/components/schemas/WhatsappInteractive'
location:
$ref: '#/components/schemas/WhatsappLocation'
reaction:
$ref: '#/components/schemas/WhatsappReaction'
sticker:
$ref: '#/components/schemas/WhatsappMedia'
template:
description: Template message object. Provide either template_id or name + language to identify the template.
properties:
components:
description: Template parameter values for header, body, and button components.
items:
properties:
index:
description: Button index (required for button components)
type: integer
parameters:
items:
properties:
text:
type: string
type:
enum:
- text
- image
- video
- document
- currency
- date_time
type: string
type: object
type: array
sub_type:
enum:
- quick_reply
- url
type: string
type:
enum:
- header
- body
- button
type: string
type: object
type: array
language:
description: Template language. Required unless template_id is provided.
properties:
code:
description: Language code (e.g. en_US)
example: en_US
type: string
policy:
example: deterministic
type: string
required:
- code
type: object
name:
description: Template name as registered with Meta. Required unless template_id is provided.
example: order_confirmation
type: string
template_id:
description: Telnyx template ID (the id field from template list/get responses). When provided, name and language are resolved automatically.
example: 019cd44b-3a1c-781b-956e-bd33e9fd2ac6
type: string
type: object
text:
description: Text message content. Can only be sent within a 24-hour customer service window.
properties:
body:
description: The text message body.
example: Hello from Telnyx!
type: string
preview_url:
default: false
description: Whether to show a URL preview in the message.
type: boolean
required:
- body
type: object
type:
enum:
- audio
- document
- image
- sticker
- video
- interactive
- location
- template
- reaction
- contacts
- text
type: string
video:
$ref: '#/components/schemas/WhatsappMedia'
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
WhatsappContact:
properties:
addresses:
items:
properties:
city:
type: string
country:
type: string
country_code:
type: string
state:
type: string
street:
type: string
type:
type: string
zip:
type: string
type: object
type: array
birthday:
type: string
emails:
items:
properties:
email:
type: string
type:
type: string
type: object
type: array
name:
type: string
org:
properties:
company:
type: string
department:
type: string
title:
type: string
type: object
phones:
items:
properties:
phone:
type: string
x-format: E+164
type:
type: string
wa_id:
type: string
type: object
type: array
urls:
items:
properties:
type:
type: string
url:
format: url
type: string
type: object
type: array
type: object
WhatsappLocation:
properties:
address:
type: string
latitude:
type: string
longitude:
type: string
name:
type: string
type: object
RCSTo:
items:
$ref: '#/components/schemas/RCSToItem'
type: array
responses:
messaging_GenericErrorResponse:
content:
application/json:
schema:
$ref: '#/components/schemas/messaging_Errors'
description: Unexpected error
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