> ## Documentation Index > Fetch the complete documentation index at: https://docs.wavix.com/llms.txt > Use this file to discover all available pages before exploring further. # Send a WhatsApp message > Sends a WhatsApp template message from one of your registered senders to a recipient, and returns the message with its ID. The API sends only template messages, so every send names one of your templates. **Behavior:** Returns `201` with the new message. Poll `whatsapp_messages_get` for the delivery outcome. A repeat send with the same `idempotency_key` returns `200` with the original message and sends nothing. **Requires:** Your account must have WhatsApp and its sending capability enabled, must have a subscription plan, and must not be blocked or suspended. `from` must be a sender registered on your account. ## OpenAPI ````yaml https://wavix.github.io/wavix-openapi/wavix-api.yaml post /v1/whatsapp/messages openapi: 3.1.0 info: title: Wavix APIs description: >- Wavix provides robust APIs that let you integrate voice and text messaging features directly into your app. Send text, place calls, and access detailed reports programmatically. termsOfService: https://wavix.com/terms-and-conditions license: name: MIT identifier: MIT contact: name: Wavix url: https://wavix.com email: support@wavix.com version: 1.1.1 servers: - url: https://api.wavix.com description: https://api.wavix.com variables: {} security: - bearerAuth: [] tags: - name: SIP trunks description: SIP trunks - name: Buy description: Numbers - name: Cart description: Numbers - name: My numbers description: Numbers - name: Billing description: Billing, transactions, and invoices - name: Profile description: Account profile and customer information - name: CDRs description: Call detail records and call history - name: Speech Analytics description: Call transcription and speech analytics - name: SMS and MMS description: Messaging - name: Number Validator description: Phone number validation - name: Link shortener description: Short link and click metrics - name: 2FA description: Two-factor authentication - name: 10DLC description: 10DLC Campaigns and Brands - name: API Keys description: API key management - name: Call webhooks description: Webhook configuration for call events - name: Call control description: Programmable Voice - name: Call streaming description: Real-time call audio streaming over WebSocket - name: Call recording description: Call recording - name: Sub-accounts description: Sub-account management - name: Voice campaigns description: Outbound voice campaigns - name: Wavix Embeddable description: WebRTC embeddable widget - name: WhatsApp description: WhatsApp senders, templates, and messages paths: /v1/whatsapp/messages: post: tags: - WhatsApp summary: Send a WhatsApp message description: >- Sends a WhatsApp template message from one of your registered senders to a recipient, and returns the message with its ID. The API sends only template messages, so every send names one of your templates. **Behavior:** Returns `201` with the new message. Poll `whatsapp_messages_get` for the delivery outcome. A repeat send with the same `idempotency_key` returns `200` with the original message and sends nothing. **Requires:** Your account must have WhatsApp and its sending capability enabled, must have a subscription plan, and must not be blocked or suspended. `from` must be a sender registered on your account. operationId: whatsapp_messages_send parameters: [] requestBody: description: Attributes of the message to send. content: application/json: schema: $ref: '#/components/schemas/WhatsAppMessageSendRequest' examples: default: summary: Shipment notification from a template value: from: '+14155550100' to: '+447537151866' idempotency_key: order-1001-shipped template: name: order_shipped language: en_US placeholders: - Maria - '#1001' required: true responses: '200': description: >- The message created by the earlier send with the same `idempotency_key`. content: application/json: schema: $ref: '#/components/schemas/WhatsAppMessageSendResponse' examples: default: summary: Original message of a repeated send value: message: uuid: 3a525ca2-6909-4c72-9399-905adf7f3a74 from: '+14155550100' to: '+447537151866' status: delivered template: name: order_shipped language: en_US created_at: '2026-01-15T10:30:00.123Z' '201': description: The new message, with its `uuid` and initial status. content: application/json: schema: $ref: '#/components/schemas/WhatsAppMessageSendResponse' examples: default: summary: New message value: message: uuid: 3a525ca2-6909-4c72-9399-905adf7f3a74 from: '+14155550100' to: '+447537151866' status: sent template: name: order_shipped language: en_US created_at: '2026-01-15T10:30:00.123Z' '400': description: >- The body is invalid. A required field is missing or unknown, `from` or `to` isn't a valid phone number, `idempotency_key` is longer than 128 characters, or a `header` or `buttons` entry has a missing or unsupported field. content: application/problem+json: schema: $ref: '#/components/schemas/WhatsAppProblem' examples: invalid-request: value: type: https://wavix.com/problems/invalid-request title: Invalid Request status: 400 detail: >- phone numbers must be 6-20 digits, with or without a leading + instance: 3a525ca2-6909-4c72-9399-905adf7f3a74 error_class: permanent error_code: WAVIX_INVALID_REQUEST '401': $ref: '#/components/responses/WhatsAppUnauthorizedResponse' '403': description: >- Returns when the account is suspended, blocked, or has no subscription plan, the API key has no access to the endpoint, or the sending capability is not enabled for the account. content: application/problem+json: schema: $ref: '#/components/schemas/WhatsAppProblem' examples: account-suspended: summary: Account is suspended value: type: https://wavix.com/problems/access-denied title: Access Denied status: 403 detail: The account is suspended. instance: 3a525ca2-6909-4c72-9399-905adf7f3a74 error_class: permanent error_code: WAVIX_ACCESS_DENIED capability-missing: summary: The sending capability is not enabled value: type: https://wavix.com/problems/capability-missing title: Capability Missing status: 403 detail: The sending capability is not enabled for this account. instance: 3a525ca2-6909-4c72-9399-905adf7f3a74 error_class: permanent error_code: WAVIX_CAPABILITY_MISSING '404': description: >- WhatsApp isn't available for your account or isn't enabled yet, or `from` doesn't match one of your senders. content: application/problem+json: schema: $ref: '#/components/schemas/WhatsAppProblem' examples: whatsapp-not-available: summary: WhatsApp is not available for this account value: type: https://wavix.com/problems/whatsapp-not-available title: WhatsApp Not Available status: 404 detail: WhatsApp is not available for this account. instance: 3a525ca2-6909-4c72-9399-905adf7f3a74 error_class: permanent error_code: WAVIX_WHATSAPP_NOT_AVAILABLE channel-not-enabled: summary: WhatsApp is not enabled yet for this account value: type: https://wavix.com/problems/channel-not-enabled title: Channel Not Enabled status: 404 detail: The WhatsApp channel is not enabled for this account. instance: 3a525ca2-6909-4c72-9399-905adf7f3a74 error_class: permanent error_code: WAVIX_CHANNEL_NOT_ENABLED sender-not-found: summary: No sender matches `from` value: type: https://wavix.com/problems/sender-not-found title: Sender Not Found status: 404 detail: no sender "14155550100" on channel "whatsapp" instance: 3a525ca2-6909-4c72-9399-905adf7f3a74 error_class: permanent error_code: WAVIX_SENDER_NOT_FOUND '429': $ref: '#/components/responses/WhatsAppTooManyRequestsResponse' '500': $ref: '#/components/responses/WhatsAppInternalServerErrorResponse' '503': $ref: '#/components/responses/WhatsAppServiceUnavailableResponse' deprecated: false security: - bearerAuth: - whatsapp:write components: schemas: WhatsAppMessageSendRequest: title: WhatsAppMessageSendRequest description: >- Attributes of a WhatsApp template message to send. Consumed by `whatsapp_messages_send`. required: - from - to - template type: object additionalProperties: false properties: from: type: string description: >- Phone number of a sender registered on your account, in E.164 format, as returned by `whatsapp_senders_list`. The leading `+` is optional. pattern: ^\+?\d{6,20}$ example: '+14155550100' to: type: string description: >- Recipient's phone number in E.164 format. The leading `+` is optional. pattern: ^\+?\d{6,20}$ example: '+447537151866' idempotency_key: type: string description: Key that makes the send safe to retry, unique per account. maxLength: 128 example: order-1001-shipped template: $ref: '#/components/schemas/WhatsAppSendTemplate' WhatsAppMessageSendResponse: title: WhatsAppMessageSendResponse description: Returned by `whatsapp_messages_send`. required: - message type: object additionalProperties: false properties: message: $ref: '#/components/schemas/WhatsAppMessage' WhatsAppProblem: title: WhatsAppProblem description: >- An RFC 9457 problem document that describes an error from the WhatsApp API. Returned with the `application/problem+json` content type. required: - type - title - status - detail - instance type: object additionalProperties: false properties: type: type: string description: URI that identifies the problem type. example: https://wavix.com/problems/whatsapp-not-available title: type: string description: Short, human-readable summary of the problem type. example: WhatsApp Not Available status: type: integer format: int32 description: HTTP status code of the response. example: 404 detail: type: string description: Human-readable explanation of this occurrence of the problem. example: WhatsApp is not available for this account. instance: type: string description: Request ID of this occurrence of the problem. example: 3a525ca2-6909-4c72-9399-905adf7f3a74 error_class: type: string description: >- Machine-readable classification of the error. Possible values: - `permanent` — The request can't succeed as sent. Retrying doesn't help. - `retriable` — The failure is temporary. Retrying can succeed. - `rate_limited` — The request was rate limited. Retry later. - `invalid_template` — The template content is invalid. enum: - permanent - retriable - rate_limited - invalid_template example: permanent error_code: type: string description: >- Stable machine-readable error code. It's the problem type slug in upper case with the `WAVIX_` prefix. example: WAVIX_WHATSAPP_NOT_AVAILABLE WhatsAppSendTemplate: title: WhatsAppSendTemplate description: >- The template to send and the values for its dynamic parts. Consumed in `template` by `whatsapp_messages_send`. required: - name - language type: object additionalProperties: false properties: name: type: string description: >- Name of the template to send, as returned by `whatsapp_templates_list`. example: order_shipped language: type: string description: >- Language code of the template to send, as returned by `whatsapp_templates_list`. example: en_US placeholders: type: array description: >- Values substituted into the template body's `{{n}}` placeholders, in order. items: type: string example: - Maria - '#1001' header: $ref: '#/components/schemas/WhatsAppSendTemplateHeader' buttons: type: array description: >- Dynamic values for the template's `buttons` component, one entry per button, matching the template's button order. Each entry accepts only the fields its `type` uses. items: $ref: '#/components/schemas/WhatsAppSendTemplateButton' WhatsAppMessage: title: WhatsAppMessage description: A WhatsApp message you sent. Returned by `whatsapp_messages_send`. required: - uuid - from - to - status - template - created_at type: object additionalProperties: false properties: uuid: type: string format: uuid description: >- ID of the message. Pass it to `whatsapp_messages_get` to check the delivery outcome. example: 3a525ca2-6909-4c72-9399-905adf7f3a74 from: type: string description: Sender's phone number in E.164 format. example: '+14155550100' to: type: string description: Recipient's phone number in E.164 format. example: '+447537151866' status: type: string description: >- Message delivery status. Possible values: - `sent` — The message isn't delivered yet. - `delivered` — The message was delivered to the recipient. - `undelivered` — The message was sent but not delivered. - `expired` — The message expired before it was delivered. - `rejected` — The message was permanently rejected before or by the provider. - `unknown` — The provider hasn't reported a status. enum: - sent - delivered - undelivered - expired - rejected - unknown example: sent template: anyOf: - $ref: '#/components/schemas/WhatsAppMessageTemplate' - type: 'null' description: Template used to send the message. created_at: type: string format: date-time description: Date and time the message was created, in ISO 8601 format. example: '2026-01-15T10:30:00.123Z' WhatsAppSendTemplateHeader: title: WhatsAppSendTemplateHeader description: >- Header content, required only when the template's `header` component needs one. Each `type` requires specific fields and rejects the others, as listed in the `type` description. Consumed in `template.header` by `whatsapp_messages_send`. required: - type type: object additionalProperties: false properties: type: type: string description: >- Header content type. Possible values: - `text` — Text header with a `{{1}}` placeholder. Requires `placeholder`. - `text_named_parameters` — Text header with a named placeholder. Requires `parameter_name` and `text`. - `image` — Image header. Requires `media_url`. - `video` — Video header. Requires `media_url`. - `document` — Document header. Requires `media_url` and `filename`. - `location` — Location header. Requires `latitude` and `longitude`. enum: - text - text_named_parameters - image - video - document - location example: text placeholder: type: string description: Value for a `text` header's `{{1}}` placeholder. example: '#1001' media_url: type: string description: Media URL for an `image`, `video`, or `document` header. example: https://example.com/media/order-1001.pdf filename: type: string description: Filename for a `document` header. example: order-1001.pdf latitude: type: number description: Latitude for a `location` header. example: 52.3676 longitude: type: number description: Longitude for a `location` header. example: 4.9041 parameter_name: type: string description: Placeholder name for a `text_named_parameters` header. example: order_number text: type: string description: Value for a `text_named_parameters` header. example: '#1001' WhatsAppSendTemplateButton: title: WhatsAppSendTemplateButton description: >- Dynamic values for one button of the template. Each `type` requires specific fields and rejects the others, as listed in the `type` description. Consumed in `template.buttons` by `whatsapp_messages_send`. required: - type type: object additionalProperties: false properties: type: type: string description: >- Button type. Possible values: - `quick_reply` — Sends a predefined reply. Requires `parameter`. - `url` — Opens a URL. Requires `parameter`. - `copy_code` — Copies a code to the clipboard. Requires `parameter`. - `flow` — Opens a WhatsApp Flow. Accepts `flow_token` and `data`. - `catalog` — Opens the business catalog. Accepts `thumbnail_product_retailer_id`. - `multi_product` — Shows a message with several products. Requires `sections` and accepts `thumbnail_product_retailer_id`. - `order_details` — Shows order details. Requires `action`. - `voice_call` — Starts a voice call. Accepts `call_validity_period` and `call_context_payload`. enum: - quick_reply - url - copy_code - flow - catalog - multi_product - order_details - voice_call example: url parameter: type: string description: >- Dynamic value of a `quick_reply`, `url`, or `copy_code` button. Required for those types. example: '1001' flow_token: type: string description: Flow token of a `flow` button. data: type: object description: Initial data passed to the Flow of a `flow` button. additionalProperties: true thumbnail_product_retailer_id: type: string description: >- Retailer ID of the product shown as the thumbnail of a `catalog` or `multi_product` button. sections: type: array description: >- Product sections of a `multi_product` button. Required for that type. items: type: object additionalProperties: true action: type: object description: Order details of an `order_details` button. Required for that type. additionalProperties: true call_validity_period: type: integer description: How long a `voice_call` button stays valid. call_context_payload: type: string description: >- Context payload returned with a call started from a `voice_call` button. WhatsAppMessageTemplate: title: WhatsAppMessageTemplate description: >- The template that a WhatsApp message was sent with. Returned in `template` by `whatsapp_messages_send`. required: - name - language type: object additionalProperties: false properties: name: type: string description: Template name. example: order_shipped language: type: string description: Template language code. example: en_US responses: WhatsAppUnauthorizedResponse: description: Authentication failed or wasn't provided. headers: {} content: application/problem+json: schema: $ref: '#/components/schemas/WhatsAppProblem' examples: authentication-required: summary: The API key or token is missing or isn't valid value: type: https://wavix.com/problems/authentication-required title: Authentication Required status: 401 detail: Authentication is required to access this resource. instance: 3a525ca2-6909-4c72-9399-905adf7f3a74 error_class: permanent error_code: WAVIX_AUTHENTICATION_REQUIRED WhatsAppTooManyRequestsResponse: description: Returns when the account has exceeded its request rate limit. headers: Retry-After: description: Number of seconds to wait before retrying the request. schema: type: integer example: 30 content: application/problem+json: schema: $ref: '#/components/schemas/WhatsAppProblem' examples: rate-limited: value: type: https://wavix.com/problems/rate-limited title: Rate Limited status: 429 detail: Too many requests. Try again later. instance: 3a525ca2-6909-4c72-9399-905adf7f3a74 error_class: rate_limited error_code: WAVIX_RATE_LIMITED WhatsAppInternalServerErrorResponse: description: >- Returns when an unexpected error occurs on the server; the request may be retried. headers: {} content: application/problem+json: schema: $ref: '#/components/schemas/WhatsAppProblem' examples: internal-error: value: type: https://wavix.com/problems/internal-error title: Internal Error status: 500 detail: Internal Error instance: 3a525ca2-6909-4c72-9399-905adf7f3a74 error_class: retriable error_code: WAVIX_INTERNAL_ERROR WhatsAppServiceUnavailableResponse: description: >- Returns when the service is temporarily unavailable; the request may be retried. content: application/problem+json: schema: $ref: '#/components/schemas/WhatsAppProblem' examples: service-unavailable: value: type: https://wavix.com/problems/service-unavailable title: Service Unavailable status: 503 detail: The service is temporarily unavailable. instance: 3a525ca2-6909-4c72-9399-905adf7f3a74 error_class: retriable error_code: WAVIX_SERVICE_UNAVAILABLE provider-unavailable: value: type: https://wavix.com/problems/provider-unavailable title: Provider Unavailable status: 503 detail: The provider is temporarily unavailable. instance: 3a525ca2-6909-4c72-9399-905adf7f3a74 error_class: retriable error_code: WAVIX_PROVIDER_UNAVAILABLE securitySchemes: bearerAuth: type: http scheme: bearer description: > Wavix API key. Pass as `Authorization: Bearer `. Keys support per-resource scopes (none / read / write). See [Restricted keys and scopes](https://docs.wavix.com/api-reference/authentication#restricted-keys-and-scopes). ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.