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

# Send a Whatsapp message

`POST /messages/whatsapp`

## Request body

- WhatsappMessage
  - `from` string, required — Phone number in +E.164 format associated with Whatsapp account
  - `to` string, required — Phone number in +E.164 format
  - `whatsapp_message` WhatsappMessageContent, required
    - `audio` WhatsappMedia
      - `link` string, url — media URL
      - `caption` string — media caption
      - `filename` string — file name with extension
      - `voice` boolean — true if voice message
    - `document` WhatsappMedia
      - `link` string, url — media URL
      - `caption` string — media caption
      - `filename` string — file name with extension
      - `voice` boolean — true if voice message
    - `image` WhatsappMedia
      - `link` string, url — media URL
      - `caption` string — media caption
      - `filename` string — file name with extension
      - `voice` boolean — true if voice message
    - `sticker` WhatsappMedia
      - `link` string, url — media URL
      - `caption` string — media caption
      - `filename` string — file name with extension
      - `voice` boolean — true if voice message
    - `video` WhatsappMedia
      - `link` string, url — media URL
      - `caption` string — media caption
      - `filename` string — file name with extension
      - `voice` boolean — true if voice message
    - `interactive` WhatsappInteractive
      - `type` 'cta_url' | 'list' | 'carousel' | 'button' | 'location_request_message'
      - `action` object
        - `name` string
        - `button` string
        - `buttons` object[]
          - `type` 'reply'
          - `reply` object
            - `title` string — button label, 20 character maximum
            - `id` string — unique identifier for each button, 256 character maximum
        - `catalog_id` string
        - `product_retailer_id` string
        - `sections` object[]
          - `product_items` object[]
            - `product_retailer_id` string
          - `rows` object[]
            - `id` string — arbitrary string identifying the row, 200 character maximum
            - `title` string — row title, 24 character maximum
            - `description` string — row description, 72 character maximum
          - `title` string — section title, 24 character maximum
        - `mode` string
        - `parameters` object
          - `display_text` string — button label text, 20 character maximum
          - `url` string, url — button URL to load when tapped by the user
        - `cards` object[]
          - `card_index` integer — unique index for each card (0-9)
          - `type` 'cta_url'
          - `header` object
            - `type` 'image' | 'video'
            - `image` WhatsappMedia
              - …
            - `video` WhatsappMedia
              - …
          - `body` object
            - `text` string — 160 character maximum, up to 2 line breaks
          - `action` object
            - `product_retailer_id` string — the unique retailer ID of the product
            - `catalog_id` string — the unique ID of the catalog
      - `body` object
        - `text` string — body text, 1024 character maximum
      - `footer` object
        - `text` string — footer text, 60 character maximum
      - `header` object
        - `document` WhatsappMedia
          - `link` string, url — media URL
          - `caption` string — media caption
          - `filename` string — file name with extension
          - `voice` boolean — true if voice message
        - `image` WhatsappMedia
          - `link` string, url — media URL
          - `caption` string — media caption
          - `filename` string — file name with extension
          - `voice` boolean — true if voice message
        - `video` WhatsappMedia
          - `link` string, url — media URL
          - `caption` string — media caption
          - `filename` string — file name with extension
          - `voice` boolean — true if voice message
        - `text` string — header text, 60 character maximum
        - `sub_text` string
    - `location` WhatsappLocation
      - `latitude` string
      - `longitude` string
      - `name` string
      - `address` string
    - `contacts` WhatsappContact[]
      - `addresses` object[]
        - `street` string
        - `city` string
        - `state` string
        - `zip` string
        - `country` string
        - `country_code` string
        - `type` string
      - `birthday` string
      - `emails` object[]
        - `email` string
        - `type` string
      - `name` string
      - `org` object
        - `company` string
        - `department` string
        - `title` string
      - `phones` object[]
        - `phone` string
        - `type` string
        - `wa_id` string
      - `urls` object[]
        - `url` string, url
        - `type` string
    - `reaction` WhatsappReaction
      - `message_id` string
      - `emoji` string
    - `biz_opaque_callback_data` string — custom data to return with status update
    - `type` 'audio' | 'document' | 'image' | 'sticker' | 'video' | 'interactive' | 'location' | 'template' | 'reaction' | 'contacts' | 'text'
    - `text` object — Text message content. Can only be sent within a 24-hour customer service window.
      - `body` string, required — The text message body.
      - `preview_url` boolean — Whether to show a URL preview in the message.
    - `template` object — Template message object. Provide either template_id or name + language to identify the template.
      - `template_id` string — Telnyx template ID (the id field from template list/get responses). When provided, name and language are resolved automatically.
      - `name` string — Template name as registered with Meta. Required unless template_id is provided.
      - `language` object — Template language. Required unless template_id is provided.
        - `policy` string
        - `code` string, required — Language code (e.g. en_US)
      - `components` object[] — Template parameter values for header, body, and button components.
        - `type` 'header' | 'body' | 'button'
        - `sub_type` 'quick_reply' | 'url'
        - `index` integer — Button index (required for button components)
        - `parameters` object[]
          - `type` 'text' | 'image' | 'video' | 'document' | 'currency' | 'date_time'
          - `text` string
  - `type` 'WHATSAPP' — Message type - must be set to "WHATSAPP"
  - `webhook_url` string, url — The URL where webhooks related to this message will be sent.
  - `messaging_profile_id` string, uuid — Messaging profile ID - required if the 'from' number is not SMS-enabled

## Response `200`

Successful operation

- WhatsappResponse
  - `data` object
    - `record_type` string
    - `direction` string
    - `id` string — message ID
    - `type` string
    - `organization_id` string
    - `messaging_profile_id` string
    - `from` object
      - `phone_number` string — Sending address (+E.164 formatted phone number, alphanumeric sender ID, or short code).
      - `status` 'received' | 'delivered'
      - `carrier` string — The carrier of the sender.
      - `line_type` 'Wireline' | 'Wireless' | 'VoWiFi' | 'VoIP' | 'Pre-Paid Wireless' | '' — The line-type of the sender.
    - `to` RCSToItem[]
      - `phone_number` string
      - `status` string
      - `carrier` string
      - `line_type` string
    - `body` WhatsappMessageContent
      - `audio` WhatsappMedia
        - `link` string, url — media URL
        - `caption` string — media caption
        - `filename` string — file name with extension
        - `voice` boolean — true if voice message
      - `document` WhatsappMedia
        - `link` string, url — media URL
        - `caption` string — media caption
        - `filename` string — file name with extension
        - `voice` boolean — true if voice message
      - `image` WhatsappMedia
        - `link` string, url — media URL
        - `caption` string — media caption
        - `filename` string — file name with extension
        - `voice` boolean — true if voice message
      - `sticker` WhatsappMedia
        - `link` string, url — media URL
        - `caption` string — media caption
        - `filename` string — file name with extension
        - `voice` boolean — true if voice message
      - `video` WhatsappMedia
        - `link` string, url — media URL
        - `caption` string — media caption
        - `filename` string — file name with extension
        - `voice` boolean — true if voice message
      - `interactive` WhatsappInteractive
        - `type` 'cta_url' | 'list' | 'carousel' | 'button' | 'location_request_message'
        - `action` object
          - `name` string
          - `button` string
          - `buttons` object[]
            - `type` 'reply'
            - `reply` object
              - …
          - `catalog_id` string
          - `product_retailer_id` string
          - `sections` object[]
            - `product_items` object[]
              - …
            - `rows` object[]
              - …
            - `title` string — section title, 24 character maximum
          - `mode` string
          - `parameters` object
            - `display_text` string — button label text, 20 character maximum
            - `url` string, url — button URL to load when tapped by the user
          - `cards` object[]
            - `card_index` integer — unique index for each card (0-9)
            - `type` 'cta_url'
            - `header` object
              - …
            - `body` object
              - …
            - `action` object
              - …
        - `body` object
          - `text` string — body text, 1024 character maximum
        - `footer` object
          - `text` string — footer text, 60 character maximum
        - `header` object
          - `document` WhatsappMedia
            - `link` string, url — media URL
            - `caption` string — media caption
            - `filename` string — file name with extension
            - `voice` boolean — true if voice message
          - `image` WhatsappMedia
            - `link` string, url — media URL
            - `caption` string — media caption
            - `filename` string — file name with extension
            - `voice` boolean — true if voice message
          - `video` WhatsappMedia
            - `link` string, url — media URL
            - `caption` string — media caption
            - `filename` string — file name with extension
            - `voice` boolean — true if voice message
          - `text` string — header text, 60 character maximum
          - `sub_text` string
      - `location` WhatsappLocation
        - `latitude` string
        - `longitude` string
        - `name` string
        - `address` string
      - `contacts` WhatsappContact[]
        - `addresses` object[]
          - `street` string
          - `city` string
          - `state` string
          - `zip` string
          - `country` string
          - `country_code` string
          - `type` string
        - `birthday` string
        - `emails` object[]
          - `email` string
          - `type` string
        - `name` string
        - `org` object
          - `company` string
          - `department` string
          - `title` string
        - `phones` object[]
          - `phone` string
          - `type` string
          - `wa_id` string
        - `urls` object[]
          - `url` string, url
          - `type` string
      - `reaction` WhatsappReaction
        - `message_id` string
        - `emoji` string
      - `biz_opaque_callback_data` string — custom data to return with status update
      - `type` 'audio' | 'document' | 'image' | 'sticker' | 'video' | 'interactive' | 'location' | 'template' | 'reaction' | 'contacts' | 'text'
      - `text` object — Text message content. Can only be sent within a 24-hour customer service window.
        - `body` string, required — The text message body.
        - `preview_url` boolean — Whether to show a URL preview in the message.
      - `template` object — Template message object. Provide either template_id or name + language to identify the template.
        - `template_id` string — Telnyx template ID (the id field from template list/get responses). When provided, name and language are resolved automatically.
        - `name` string — Template name as registered with Meta. Required unless template_id is provided.
        - `language` object — Template language. Required unless template_id is provided.
          - `policy` string
          - `code` string, required — Language code (e.g. en_US)
        - `components` object[] — Template parameter values for header, body, and button components.
          - `type` 'header' | 'body' | 'button'
          - `sub_type` 'quick_reply' | 'url'
          - `index` integer — Button index (required for button components)
          - `parameters` object[]
            - `type` 'text' | 'image' | 'video' | 'document' | 'currency' | 'date_time'
            - `text` string
    - `encoding` string
    - `received_at` string, date-time
    - `wait_seconds` number, float, nullable — 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.

## Other responses

- `4XX` — Unexpected error

---

[API](https://skmtc.net/team-telnyx/apis/telnyx-api-2.md) · [All operations](https://skmtc.net/team-telnyx/apis/telnyx-api-2/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/team-telnyx/telnyx-api-2/versions/8f5f4e537994/schema)