Telnyx Whatsapp Business Accounts API
Manage Whatsapp business accounts
Manage Whatsapp business accounts
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/telnyx:telnyx-whatsapp-business-accounts-api"
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: Telnyx Whatsapp Business Accounts API
version: 2.0.0
contact:
email: support@telnyx.com
x-endpoint-cost: light
x-refined-note:
- x-latency-category differs across the merged source definitions and was not carried
description: 'Operations tagged Whatsapp Business Accounts across 3 of this provider''s published API definitions: telnyx-openapi.json, telnyx-openapi.yml, telnyx-openapi_2.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.telnyx.com/v2
description: Version 2.0.0 of the Telnyx API
security:
- bearerAuth: []
tags:
- name: Whatsapp Business Accounts
description: Manage Whatsapp business accounts
paths:
/v2/whatsapp/business_accounts:
get:
tags:
- Whatsapp Business Accounts
summary: List Whatsapp Business Accounts
operationId: ListWabas
parameters:
- $ref: '#/components/parameters/PageConsolidated'
responses:
'200':
description: List of Whatsapp Business Accounts
$ref: '#/components/responses/messaging_WabasListResponse'
4XX:
$ref: '#/components/responses/messaging_GenericErrorResponse_0b38e7044b'
description: Returns WhatsApp Business Accounts linked to the authenticated Telnyx account.
servers:
- url: https://api.telnyx.com/v2
description: Version 2.0.0 of the Telnyx API
/v2/whatsapp/business_accounts/{id}:
delete:
tags:
- Whatsapp Business Accounts
summary: Delete a Whatsapp Business Account
operationId: deleteWaba
parameters:
- $ref: '#/components/parameters/WabaId'
responses:
'204':
description: Deleted
4XX:
$ref: '#/components/responses/messaging_GenericErrorResponse_0b38e7044b'
description: Unlinks and deletes the specified WhatsApp Business Account resource from Telnyx.
get:
tags:
- Whatsapp Business Accounts
summary: Get a single Whatsapp Business Account
operationId: GetSingleWaba
parameters:
- $ref: '#/components/parameters/WabaId'
responses:
'200':
description: Whatsapp Business Account details
$ref: '#/components/responses/WabaSingleResponse'
4XX:
$ref: '#/components/responses/messaging_GenericErrorResponse_0b38e7044b'
description: Returns the configuration and status of the specified WhatsApp Business Account.
servers:
- url: https://api.telnyx.com/v2
description: Version 2.0.0 of the Telnyx API
/v2/whatsapp/business_accounts/{id}/phone_numbers:
get:
tags:
- Whatsapp Business Accounts
summary: List phone numbers for a WABA
operationId: ListWabaPhones
parameters:
- $ref: '#/components/parameters/WabaId'
- $ref: '#/components/parameters/PageConsolidated'
responses:
'200':
description: List of phone numbers
$ref: '#/components/responses/messaging_WhatsappPhonesListResponse'
4XX:
$ref: '#/components/responses/messaging_GenericErrorResponse_0b38e7044b'
description: Returns phone numbers registered under the specified WhatsApp Business Account.
servers:
- url: https://api.telnyx.com/v2
description: Version 2.0.0 of the Telnyx API
/v2/whatsapp/business_accounts/{id}/settings:
get:
tags:
- Whatsapp Business Accounts
summary: Get WABA settings
operationId: GetWabaSettings
parameters:
- $ref: '#/components/parameters/WabaId'
responses:
'200':
description: WABA settings
$ref: '#/components/responses/WabaSettingsResponse'
4XX:
$ref: '#/components/responses/messaging_GenericErrorResponse_0b38e7044b'
description: Returns account-level settings for the specified WhatsApp Business Account.
patch:
tags:
- Whatsapp Business Accounts
summary: Update WABA settings
operationId: PatchWabaSettings
parameters:
- $ref: '#/components/parameters/WabaId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PatchWabaSettingsRequest'
responses:
'200':
description: Updated settings
$ref: '#/components/responses/WabaSettingsResponse'
4XX:
$ref: '#/components/responses/messaging_GenericErrorResponse_0b38e7044b'
description: Updates the supplied account-level settings for the specified WhatsApp Business Account.
servers:
- url: https://api.telnyx.com/v2
description: Version 2.0.0 of the Telnyx API
/v2/whatsapp/user_data:
get:
tags:
- Whatsapp Business Accounts
summary: Fetch Whatsapp user data
operationId: GetWhatsappUserData
responses:
'200':
description: Whatsapp user data
$ref: '#/components/responses/WhatsappUserDataResponse'
4XX:
$ref: '#/components/responses/messaging_GenericErrorResponse_0b38e7044b'
description: Returns the WhatsApp user-data settings associated with the authenticated Telnyx account.
patch:
tags:
- Whatsapp Business Accounts
summary: Update Whatsapp user data
operationId: PatchWhatsappUserData
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PatchWhatsappUserDataRequest'
example:
webhook_url: https://example.com
webhook_failover_url: https://example.com
responses:
'200':
description: Updated user data
$ref: '#/components/responses/WhatsappUserDataResponse'
4XX:
$ref: '#/components/responses/messaging_GenericErrorResponse_0b38e7044b'
description: Updates the supplied WhatsApp user-data settings for the authenticated Telnyx account.
servers:
- url: https://api.telnyx.com/v2
description: Version 2.0.0 of the Telnyx API
/whatsapp/business_accounts:
get:
tags:
- Whatsapp Business Accounts
summary: List Whatsapp Business Accounts
operationId: ListWabas_2
parameters:
- $ref: '#/components/parameters/PageConsolidated'
responses:
'200':
description: List of Whatsapp Business Accounts
$ref: '#/components/responses/WabasListResponse'
4XX:
$ref: '#/components/responses/management_messaging_GenericErrorResponse'
x-latency-category: responsive
description: Retrieve a list of the WhatsApp Business Accounts (WABAs) connected to your Telnyx account.
servers:
- url: https://api.telnyx.com/v2
description: Version 2.0.0 of the Telnyx API
/whatsapp/business_accounts/{id}:
delete:
tags:
- Whatsapp Business Accounts
summary: Delete a Whatsapp Business Account
operationId: deleteWaba_2
parameters:
- $ref: '#/components/parameters/WabaId'
responses:
'204':
description: Deleted
4XX:
$ref: '#/components/responses/management_messaging_GenericErrorResponse'
x-latency-category: responsive
description: Delete a WhatsApp Business Account connection from your Telnyx account.
get:
tags:
- Whatsapp Business Accounts
summary: Get a single Whatsapp Business Account
operationId: GetSingleWaba_2
parameters:
- $ref: '#/components/parameters/WabaId'
responses:
'200':
description: Whatsapp Business Account details
$ref: '#/components/responses/WabaSingleResponse'
4XX:
$ref: '#/components/responses/management_messaging_GenericErrorResponse'
x-latency-category: responsive
description: Retrieve the details of a specific WhatsApp Business Account.
servers:
- url: https://api.telnyx.com/v2
description: Version 2.0.0 of the Telnyx API
/whatsapp/business_accounts/{id}/phone_numbers:
get:
tags:
- Whatsapp Business Accounts
summary: List phone numbers for a WABA
operationId: ListWabaPhones_2
parameters:
- $ref: '#/components/parameters/WabaId'
- $ref: '#/components/parameters/PageConsolidated'
responses:
'200':
description: List of phone numbers
$ref: '#/components/responses/WhatsappPhonesListResponse'
4XX:
$ref: '#/components/responses/management_messaging_GenericErrorResponse'
x-latency-category: responsive
description: List the phone numbers associated with a WhatsApp Business Account.
servers:
- url: https://api.telnyx.com/v2
description: Version 2.0.0 of the Telnyx API
/whatsapp/business_accounts/{id}/settings:
get:
tags:
- Whatsapp Business Accounts
summary: Get WABA settings
operationId: GetWabaSettings_2
parameters:
- $ref: '#/components/parameters/WabaId'
responses:
'200':
description: WABA settings
$ref: '#/components/responses/WabaSettingsResponse'
4XX:
$ref: '#/components/responses/management_messaging_GenericErrorResponse'
x-latency-category: responsive
description: Retrieve the settings of a WhatsApp Business Account.
patch:
tags:
- Whatsapp Business Accounts
summary: Update WABA settings
operationId: PatchWabaSettings_2
parameters:
- $ref: '#/components/parameters/WabaId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PatchWabaSettingsRequest'
responses:
'200':
description: Updated settings
$ref: '#/components/responses/WabaSettingsResponse'
4XX:
$ref: '#/components/responses/management_messaging_GenericErrorResponse'
x-latency-category: responsive
description: Update the settings of a WhatsApp Business Account.
servers:
- url: https://api.telnyx.com/v2
description: Version 2.0.0 of the Telnyx API
components:
responses:
management_messaging_GenericErrorResponse:
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/messaging_Errors'
example:
errors:
- code: string
title: string
detail: string
source:
pointer: /data/attributes/phone_number
parameter: string
messaging_GenericErrorResponse_0b38e7044b:
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/messaging_Errors_0b38e7044b'
example:
errors:
- code: string
title: string
detail: string
source:
pointer: /data/attributes/phone_number
parameter: string
WabasListResponse:
description: Successful response with list of Whatsapp business accounts
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/WabaResponse'
meta:
$ref: '#/components/schemas/messaging_PaginationMeta'
messaging_WabasListResponse:
description: Successful response with list of Whatsapp business accounts
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/WabaResponse'
meta:
$ref: '#/components/schemas/messaging_PaginationMeta_0b38e7044b'
WabaSettingsResponse:
description: Successful response with Whatsapp business account settings
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/WabaSettings'
WabaSingleResponse:
description: Successful response with Whatsapp business account
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/WabaResponse'
messaging_WhatsappPhonesListResponse:
description: Successful response with Whatsapp phone numbers
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/WhatsappPhoneResponse'
meta:
$ref: '#/components/schemas/messaging_PaginationMeta_0b38e7044b'
WhatsappUserDataResponse:
description: Successful response with Whatsapp user data
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/WhatsappUserData'
WhatsappPhonesListResponse:
description: Successful response with Whatsapp phone numbers
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/WhatsappPhoneResponse'
meta:
$ref: '#/components/schemas/messaging_PaginationMeta'
messaging_GenericErrorResponse:
content:
application/json:
schema:
$ref: '#/components/schemas/messaging_Errors'
description: Unexpected error
schemas:
messaging_Error:
required:
- code
- title
properties:
code:
type: string
x-format: integer
title:
type: string
detail:
type: string
source:
type: object
properties:
pointer:
description: JSON pointer (RFC6901) to the offending entity.
type: string
format: json-pointer
parameter:
description: Indicates which query parameter caused the error.
type: string
meta:
type: object
messaging_PaginationMeta_0b38e7044b:
type: object
required:
- total_pages
- total_results
- page_size
- page_number
properties:
total_pages:
type: integer
example: 3
total_results:
type: integer
example: 55
page_number:
type: integer
example: 2
page_size:
type: integer
example: 25
messaging_Errors:
properties:
errors:
type: array
items:
$ref: '#/components/schemas/messaging_Error'
messaging_PaginationMeta:
type: object
required:
- total_pages
- total_results
- page_size
- page_number
properties:
total_pages:
type: integer
example: 3
total_results:
type: integer
example: 55
page_number:
type: integer
example: 2
page_size:
type: integer
example: 25
WabaSettings:
type: object
properties:
id:
type: string
format: uuid
description: Internal ID of Whatsapp business account
record_type:
type: string
example: whatsapp_business_account_settings
name:
type: string
timezone:
type: string
example: America/Chicago
webhook_url:
type: string
format: url
description: URL to receive Whatsapp events
webhook_failover_url:
type: string
format: url
description: Failover URL to receive Whatsapp events
webhook_enabled:
type: boolean
description: Enable/disable receiving Whatsapp events
webhook_events:
type: array
items:
type: string
description: Whatsapp event to subscribe to
updated_at:
type: string
format: date-time
WabaResponse:
type: object
properties:
id:
type: string
format: uuid
description: Internal ID of Whatsapp business account
record_type:
type: string
example: whatsapp_business_account
name:
type: string
description: Name of Whatsapp business account
waba_id:
type: string
description: WABA ID of Whatsapp business account
status:
type: string
description: Status of Whatsapp business account
phone_numbers_count:
type: integer
description: Count of phone numbers associated with Whatsapp business account
business_verification_status:
type: string
description: Business verification status of Whatsapp business account
account_review_status:
type: string
description: Account review status of Whatsapp business account
country:
type: string
description: Country associated with Whatsapp business account
created_at:
type: string
format: date-time
PatchWhatsappUserDataRequest:
type: object
properties:
webhook_url:
type: string
format: url
description: URL to send Whatsapp signup events
webhook_failover_url:
type: string
format: url
description: Failover URL to send Whatsapp signup events
WhatsappUserData:
type: object
properties:
record_type:
type: string
example: whatsapp_user_data
webhook_url:
type: string
format: url
description: URL to receive Whatsapp signup events
webhook_failover_url:
type: string
format: url
description: Failover URL to receive Whatsapp signup events
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
WhatsappPhoneResponse:
type: object
properties:
record_type:
type: string
example: whatsapp_business_phone_number
phone_number:
type: string
description: Phone number in E164 format
phone_number_id:
type: string
description: Whatsapp phone number ID
waba_id:
type: string
description: WABA ID of Whatsapp business account
user_id:
type: string
description: User ID
display_name:
type: string
quality_rating:
type: string
description: Whatsapp quality rating
status:
type: string
created_at:
type: string
format: date-time
enabled:
type: boolean
calling_enabled:
type: boolean
is_on_biz_app:
type: boolean
description: Indicates whether the number is connected to both the WhatsApp Business app and Cloud API through WhatsApp Coexistence.
coexistence_state:
type:
- string
- 'null'
enum:
- pending_onboarding
- sync_pending
- syncing
- sync_complete
- active
- history_declined
- sync_deadline_expired
- offboarded
- disconnected
- null
description: Current lifecycle state for a coexistence number. This is null for a standard Cloud API number.
sync_deadline:
type:
- string
- 'null'
format: date-time
description: Deadline for initiating the current coexistence synchronization cycle. This is null when no deadline applies.
sync_progress:
type:
- object
- 'null'
description: Synchronization progress. This object is returned only while a coexistence number is synchronizing.
properties:
contacts_status:
type: string
history_status:
type: string
history_phase:
type:
- integer
- 'null'
history_chunk_order:
type:
- integer
- 'null'
history_progress:
type:
- integer
- 'null'
minimum: 0
maximum: 100
messaging_Errors_0b38e7044b:
properties:
errors:
type: array
items:
$ref: '#/components/schemas/messaging_Error_0b38e7044b'
PatchWabaSettingsRequest:
type: object
properties:
name:
type: string
timezone:
type: string
description: IANA timezone identifier
example: America/New_York
webhook_url:
type: string
format: url
description: URL to send Whatsapp events
webhook_failover_url:
type: string
format: url
description: Failover URL to send Whatsapp events
webhook_enabled:
type: boolean
description: Enable/disable receiving Whatsapp events
webhook_events:
type: array
items:
type: string
description: Whatsapp event to subscribe to
messaging_Error_0b38e7044b:
required:
- code
- title
properties:
code:
type: string
x-format: integer
title:
type: string
detail:
type: string
source:
type: object
properties:
pointer:
description: JSON pointer (RFC6901) to the offending entity.
type: string
format: json-pointer
parameter:
description: Indicates which query parameter caused the error.
type: string
meta:
type: object
WhatsappPhoneResponse_2:
properties:
calling_enabled:
type: boolean
created_at:
format: date-time
type: string
display_name:
type: string
enabled:
type: boolean
phone_number:
description: Phone number in E164 format
type: string
phone_number_id:
description: Whatsapp phone number ID
type: string
quality_rating:
description: Whatsapp quality rating
type: string
record_type:
example: whatsapp_business_phone_number
type: string
status:
type: string
user_id:
description: User ID
type: string
waba_id:
description: WABA ID of Whatsapp business account
type: string
type: object
parameters:
PageConsolidated:
name: page
in: query
style: deepObject
explode: true
description: 'Consolidated page parameter (deepObject style). Originally: page[number], page[size]'
schema:
type: object
properties:
number:
type: integer
minimum: 1
default: 1
description: The page number to load
size:
type: integer
minimum: 1
maximum: 250
default: 20
description: The size of the page
WabaId:
name: id
in: path
required: true
schema:
type: string
description: Whatsapp Business Account ID
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: API key
description: 'Telnyx API key supplied as `Authorization: Bearer <token>`. In production, auth may be validated by the API gateway and forwarded via Telnyx auth headers.'
Payment:
type: apiKey
in: header
name: Authorization
description: 'Machine Payment Protocol credential used on paid retries, sent as `Authorization: Payment ...`. Obtained by paying a challenge returned in the `WWW-Authenticate` header of a 402 response. This is not a Telnyx API key; initial challenge requests use standard bearer authentication instead.'
agent-memory_bearerAuth:
type: http
scheme: bearer
description: Telnyx API key
bearerAuth:
type: http
scheme: bearer
branded-calling_bearerAuth:
type: http
scheme: bearer
description: Telnyx API key. Generate one at https://portal.telnyx.com/#/app/api-keys.
collections_bearerAuth:
type: http
scheme: bearer
description: Telnyx API key. Collections and results are automatically scoped to the authenticated user's organization.
number-reputation_bearerAuth:
type: http
scheme: bearer
description: Telnyx API key. Generate one at https://portal.telnyx.com/#/app/api-keys.
oauthClientAuth:
type: oauth2
flows:
clientCredentials:
tokenUrl: https://api.telnyx.com/v2/oauth/token
scopes:
admin: Administrative access to Telnyx resources
authorizationCode:
authorizationUrl: https://api.telnyx.com/v2/oauth/authorize
tokenUrl: https://api.telnyx.com/v2/oauth/token
refreshUrl: https://api.telnyx.com/v2/oauth/token
scopes:
admin: Administrative access to Telnyx resources
description: OAuth 2.0 authentication for Telnyx API and MCP integrations
outbound-voice-profiles_bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
pronunciation-dicts_bearerAuth:
type: http
scheme: bearer
description: Telnyx API v2 key. Obtain from https://portal.telnyx.com
rcs-registration_bearerAuth:
type: http
scheme: bearer
bearerFormat: API key
stored-payment-transactions_bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
transcriptions-search_bearerAuth:
type: http
scheme: bearer
description: Telnyx API key. Results are automatically scoped to the authenticated user's organization.
web-search_bearerAuth:
type: http
scheme: bearer
description: Telnyx API key
pay-connectors_bearerAuth:
type: http
scheme: bearer
description: Telnyx API key, not the processor bearer token.
telnyxApiKey:
type: http
scheme: bearer
description: Management-only Telnyx account credential.
x-refined-from:
- telnyx-openapi.json
- telnyx-openapi.yml
- telnyx-openapi_2.json
x-service-info:
categories:
- communication
- developer-tools
docs:
apiReference: https://developers.telnyx.com
homepage: https://telnyx.com
llms: https://telnyx.com/llms.txt