---
title: "Send a WhatsApp message"
method: POST
path: "/v1/whatsapp/messages"
tags: ["WhatsApp"]
---

# Send a WhatsApp message

`POST /v1/whatsapp/messages`

Sends a WhatsApp template message from a registered sender to a recipient.

## Request body

- WhatsAppMessageSendRequest
  - `from` string, required — Sender's phone number, 6-20 digits.
  - `to` string, required — Recipient's phone number, 6-20 digits.
  - `template` object, required
    - `name` string, required — Approved template name.
    - `language` string, required — Template language code.
    - `placeholders` string[] — Values substituted into the template body's `{{n}}` placeholders, in order.
    - `header` object — Header content, required only when the template's `HEADER` component needs one.
      - `type` 'TEXT' | 'TEXT_NAMED_PARAMETERS' | 'IMAGE' | 'VIDEO' | 'DOCUMENT' | 'LOCATION'
      - `placeholder` string — Value for a `TEXT` header's `{{1}}` placeholder.
      - `mediaUrl` string — Media URL for an `IMAGE`/`VIDEO`/`DOCUMENT` header.
      - `filename` string — Filename for a `DOCUMENT` header.
      - `latitude` number — Latitude for a `LOCATION` header.
      - `longitude` number — Longitude for a `LOCATION` header.
      - `parameterName` string — Placeholder name for a named-parameter `TEXT` header.
      - `text` string — Value for a named-parameter `TEXT` header.
    - `buttons` object[] — Dynamic values for the template's `BUTTONS` component, one entry per button, matching the template's button order.
      - `type` 'QUICK_REPLY' | 'URL' | 'COPY_CODE' | 'FLOW' | 'CATALOG' | 'MULTI_PRODUCT' | 'ORDER_DETAILS' | 'VOICE_CALL', required

## Response `201`

The submitted message, with its `uuid` and initial status.

- WhatsAppMessageSendResponse
  - `message` WhatsAppMessage, required
    - `uuid` string, uuid, required — Message ID.
    - `from` string, required — Sender's phone number in E.164 digits.
    - `to` string, required — Recipient's phone number in E.164 digits.
    - `status` 'failed' | 'sent' | 'delivered' | 'undelivered' | 'expired' | 'rejected' | 'unknown', required — Message delivery status.
    - `template` object, nullable — Template used to send the message.
      - `name` string — Template name.
      - `language` string — Template language code.
    - `created_at` string, required — Date and time the message was created, in ISO 8601 format.

## Other responses

- `400` — Returns when `from`/`to` are not valid phone numbers, or a button entry is malformed.
- `401` — Returns when the request is not authenticated.
- `402` — Returns when the account balance is insufficient.
- `403` — Returns when WhatsApp is account-suspended, or the sending capability is not enabled for the account.
- `404` — Returns when WhatsApp is not available or not enabled for the account, no sender matches `from`, or no approved template matches the given name and language.
- `409` — Returns when the template is not approved for sending.
- `429` — Returns when the account has exceeded its request rate limit.
- `502` — Returns when the provider rejects the message permanently.
- `503` — Returns when the provider is temporarily unavailable; the request may be retried.

## Changes

- **2026-09-23** `8bde78f383c6` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/wavix/apis/wavix-apis/changes/v1/whatsapp/messages/post.md)

---

[API](https://skmtc.dev/wavix/apis/wavix-apis.md) · [All operations](https://skmtc.dev/wavix/apis/wavix-apis/llms.txt) · [OpenAPI document](https://skmtc.dev/wavix/apis/wavix-apis/revisions/43ad912a102a?raw)