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

# Send WhatsApp message

`POST /v2/whatsapp/messages`

Sends a single templated message to a single recipient. Templates need to be registered and pre-approved by WhatsApp.

## Request body

- WhatsappRequest
  - `sender` string — Registered WhatsApp sender number. - Must be in **international format** following the [E.164 standard](http://en.wikipedia.org/wiki/E.164) (e.g., +14155238886). - Number must be registered with the WhatsApp Business API. - **Optional.** When omitted, the account's sender is used automatically. Accounts with multiple senders must specify one.
  - `recipient` string, phone, required — Recipient phone number in international format. - Must follow **E.164 format** (e.g., `+14155238886` for a US number). - No spaces, dashes, or special characters. - The recipient must **have an active WhatsApp account**. - Ensure the recipient **has opted in** to receive WhatsApp messages.
  - `content_type` 'text' | 'template' | 'custom', required — Type of the message content.
  - `content` union, required — The message content to be sent. - Must follow the WhastApp-approved **template format** or be a **custom object** following the Meta Cloud API guidelines. - **Example JSON (Text Content):** ```json { "text": { "message": "hello, world!", } } ``` - **Example JSON (Template Content):** ```json { "template": { "name": "order_update", "parameters": ["123456"] } } ``` - **Example JSON (Custom Content):** ```json { "custom": { "type": "template", "template": { "name": "template_img_simple_1", "language": { "code": "en", "policy": "deterministic" }, "components": [ { "type": "HEADER", "parameters": [ { "type": "image", "image": { "link": "https://image-test.jpg" } } ] } ] } } } ```
    - object
      - `text` Text, required — Text content for the message.
        - `message` string, required — The text message body.
    - object
      - `template` Template, required — Template details for the message content.
        - `name` string, required — The **exact name** of the WhatsApp template. - **Format:** Lowercase, alphanumeric, underscores only. - **Example:** `order_confirmation` - **Must be pre-approved** in your WhatsApp Business account.
        - `parameters` string[] — The **dynamic values** to populate placeholdes in the template message. - The number of parameters **must match** the template placeholders. - Supports **text only** (strings). Other types (e.g., images, documents) are not allowed. - **Example Usage:** - Template: `"Hello, {1}! Your order {2} has been shipped."` - Parameters: `["Tony", "#12345"]` - Final message: `"Hello, Tony! Your order #12345 has been shipped."`
        - `locale` string — Optional locale for the template (e.g., en_US), if not provided, the default locale is `en`.
    - object
      - `custom` Custom, required — Custom content following the Meta Cloud API guidelines.
  - `sms_fallback` SMSFallback — SMS fallback message details.
    - `sender` string — The sender number to use for SMS fallback, which can be in [E.164](http://en.wikipedia.org/wiki/E.164) international format or an alphanumeric sender ID.
    - `message` string, required — The message to send via SMS.
  - `message_ref` string — A unique reference ID supplied by your system to track messages. - **Maximum Length:** 500 characters. - This `message_ref` will be included in webhook events, allowing you to correlate sent messages with received events. **Example Usage:** - Sending a message with `message_ref: "order-12345"` - Receiving a delivery webhook containing `message_ref: "order-12345"`, confirming it was delivered.

## Response `200`

OK

- object
  - `data` object, required — Success response payload
    - `id` string, required — Unique identifier for the message.
    - `message_ref` string — Optional reference ID set by the user for the message.
    - `sender` string, required — Registered WhatsApp sender number in international format.
    - `recipient` string, phone, required — WhatsApp recipient phone number in international format.
    - `content_type` 'text' | 'template' | 'custom', required — Type of the message content.
    - `content` union, required — Content details for the message.
      - object
        - `text` Text, required — Text content for the message.
          - `message` string, required — The text message body.
      - object
        - `template` Template, required — Template details for the message content.
          - `name` string, required — The **exact name** of the WhatsApp template. - **Format:** Lowercase, alphanumeric, underscores only. - **Example:** `order_confirmation` - **Must be pre-approved** in your WhatsApp Business account.
          - `parameters` string[] — The **dynamic values** to populate placeholdes in the template message. - The number of parameters **must match** the template placeholders. - Supports **text only** (strings). Other types (e.g., images, documents) are not allowed. - **Example Usage:** - Template: `"Hello, {1}! Your order {2} has been shipped."` - Parameters: `["Tony", "#12345"]` - Final message: `"Hello, Tony! Your order #12345 has been shipped."`
          - `locale` string — Optional locale for the template (e.g., en_US), if not provided, the default locale is `en`.
      - object
        - `custom` Custom, required — Custom content following the Meta Cloud API guidelines.
    - `sms_fallback` SMSFallback — SMS fallback message details.
      - `sender` string — The sender number to use for SMS fallback, which can be in [E.164](http://en.wikipedia.org/wiki/E.164) international format or an alphanumeric sender ID.
      - `message` string, required — The message to send via SMS.
    - `created_at` string, date-time, required — Timestamp in RFC3339 format (e.g., 2025-08-26T10:30:00Z) when the message was created on the server.
  - `request` object — Optional metadata (e.g. requestId, traceId)
  - `meta` object — Optional pagination, feature flags, etc.

## Other responses

- `400` — Input Validation Error
- `429` — Too Many Requests
- `500` — Internal Server Error

## Changes

- **2026-08-18** `1cf990b86637` — 1 breaking
  - the `allOf[subschema #2]/data/sender` response's property type/format changed from `string`/`phone` to `string`/`` for status `200`

[Change history](https://skmtc.dev/kudosity/apis/transmit-message-api/changes/v2/whatsapp/messages/post.md)

---

[API](https://skmtc.dev/kudosity/apis/transmit-message-api.md) · [All operations](https://skmtc.dev/kudosity/apis/transmit-message-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/kudosity/transmit-message-api/revisions/1cf990b86637/schema)