Send a WhatsApp Message

POST https://pilotstatus.com.br/v1/messages/send

This is the only send endpoint. It supports three mutually exclusive top-level modes:

Template send — templateId (+ optional variables)
Free-form text send — text
Direct media send — media + mediaType (no templateId, no text)

Exactly one mode must be used per request. There are no separate /messages/text, /messages/media, or /messages/interactive endpoints.

Dashboard Message page with a template picker and preview, variables mapped to spreadsheet columns, a recipients list with Excel/CSV upload, Send and Schedule actions, and the auto-generated curl of the exact API call — The Message page uses this same endpoint — pick a template, map variables to spreadsheet columns, upload recipients, and copy the auto-generated curl.

Headers

Content-Type: application/json
x-api-key: ps_... (or x-api-key-id: <api_key_id>) — a number-scoped key

Destination (exactly one)

string

Destination phone in E.164 with a leading + (e.g., +5511999999999).

string

WhatsApp group JID ending in @g.us.

WhatsApp channel JID ending in @newsletter.

Mode fields

string

Template from the dashboard /templates. Mutually exclusive with text and direct-media mode.

object

Key→value map for template variables. Missing required variables produce MISSING_TEMPLATE_VARIABLES.

string

Body of a free-form message. Required if templateId is not sent (and not doing a direct media send).

string

A public http(s) URL or a base64 data URI (e.g. data:audio/ogg;base64,AAAA...) to an image, video, document, or audio file. Base64 is accepted for all media types on Meta Cloud API numbers. On unofficial (Pilot Status web) numbers, base64 is not accepted — use a public http(s) URL. Overrides any embedded mediaUrl in the template.

string

image, video, document, audio, voice, or sticker. Set it explicitly when the URL extension is not obvious (e.g. PDFs whose URL does not end in .pdf). When mediaType is audio, the file is delivered as a WhatsApp voice note (PTT) on all providers. A presence indicator is shown to the contact just before delivery: unofficial (Pilot Status web) numbers show “recording audio” (gravando); Meta Cloud API numbers show “typing” (digitando) — the Cloud API has no recording variant, and it only appears when the conversation has a recent inbound message to attach to. Typing is shown before every conversational send on Meta and Evolution numbers; you can also trigger it independently via Typing Indicator. sticker sends a WhatsApp sticker — direct media send only, never with templateId, never with a caption, and the file must be image/webp at exactly 512×512 pixels (static up to 100 KB, animated up to 500 KB).

Direct media send

Send media on its own by providing media + mediaType without templateId and without text. In this mode buttons, header, footer, and variables are not allowed; an optional caption is allowed for image, video, and document but not for audio, voice, or sticker.

Media sends are available on every plan, including Free — they count against the number’s message quota just like any other message. There is no separate paid gate for sending media.

Scheduling and delivery window

string

ISO 8601 datetime to schedule the send.

string

ISO 8601 deadline for delivery. If it expires, the message fails (see Log Error Codes).

Other fields

string[]

Tag the destination with Labels (tenant scope). Processed asynchronously. With API key retentionDays = 0, Labels are created but the phone/group linkage may not be persisted (PII).

object

For MARKETING templates only. aiRewriteEnabled: true enables automatic variation of the final message text to reduce repetitive patterns (anti-spam) while preserving intent. If variation cannot be applied, the original text is sent. MARKETING sends also receive an automatic variable queue delay (default 8–25 s) to space out sending pace.

array

Up to 3 buttons that override the template’s buttons. Each button has type and displayText plus type-specific fields:

{ "type": "reply", "displayText": "Yes", "id": "yes" } — quick reply
{ "type": "url", "displayText": "Site", "url": "https://example.com" } — URL button
{ "type": "call", "displayText": "Call", "phoneNumber": "+5511999999999" } — call button
{ "type": "copy", "displayText": "Code", "copyCode": "ABC123" } — copy button

buttons can be combined with any mediaType. The API does not reject buttons with mediaType: "video" or mediaType: "document" (unofficial numbers accept them); note that Meta Cloud API may reject some button + video/document combinations at delivery time.

object

Header for a free-form interactive message. Requires buttons. Types: { "type": "text", "content": "Header title" } (up to 60 chars), or image / video / document with a public URL as content.

string

Message footer (max 60 characters). Requires buttons.

object

Interactive single-select list for a free-form send. Requires text; mutually exclusive with templateId, buttons, header, and direct media (footer is allowed). See Lists below.

Free-form restrictions

media and mediaType cannot be used with text (free-form).
header and footer are only supported when buttons is present (Meta Cloud API limitation).
On Meta numbers, free-form messages only work within the WhatsApp 24h conversation window. Outside the window, a META_OUTSIDE_24H_WINDOW error is returned in the message.failed webhook — use an approved template instead. You can check whether the window is open before sending with GET /v1/service-window.

Buttons

buttons attaches up to 3 interactive buttons — on a free-form text send, or to override a template’s buttons on a template send. Each item needs type + displayText and one type-specific field:

`type`	Extra field	Behavior
`reply`	`id` (string)	Quick-reply. The tap arrives as a normal inbound webhook whose `content` is the button label — `id` is not echoed back.
`url`	`url` (https)	Opens a link.
`call`	`phoneNumber` (E.164)	Dials the number.
`copy`	`copyCode` (string)	Copies a code to the clipboard.

{
  "text": "Confirm your appointment?",
  "destinationNumber": "+5511999999999",
  "buttons": [
    { "type": "reply", "displayText": "Confirm", "id": "confirm" },
    { "type": "url", "displayText": "Details", "url": "https://example.com/order/123" }
  ]
}

header and footer are only allowed together with buttons (Meta Cloud API limitation).
Match reply taps by the label in content + quotedMessageId — there is no button_id field and no button_reply event.
On Meta Cloud API numbers, free-form buttons only work inside the 24-hour service window. Outside it, send an approved template. Template buttons use a different vocabulary — QUICK_REPLY, URL, PHONE_NUMBER, COPY_CODE, PAYMENT_REQUEST — defined when the template is created; see Templates.

Lists

list attaches an interactive single-select list to a free-form text send: text becomes the message body and buttonText labels the button that opens the menu of rows. Mutually exclusive with templateId, buttons, and direct media:

{
  "text": "How can we help you today?",
  "destinationNumber": "+5511999999999",
  "list": {
    "buttonText": "See areas",
    "sections": [
      {
        "title": "Support",
        "rows": [
          { "id": "clients", "title": "Clients", "description": "Look up and register clients" },
          { "title": "Orders", "description": "Track an existing order" }
        ]
      }
    ]
  }
}

Caps (Meta’s, enforced uniformly on every number type): buttonText 1–20 chars, 1–10 sections, max 10 rows total across all sections, row title 1–24 chars, row description up to 72 chars, row id up to 200 chars (generated when absent). Section title is optional.
Works on both number types with the same request: Meta Cloud API numbers send the official interactive list; unofficial (Pilot Status web) numbers send the native list.
The recipient’s selection arrives as a normal inbound message/webhook.

Examples

curl -X POST "https://pilotstatus.com.br/v1/messages/send" \
  -H "Content-Type: application/json" \
  -H "x-api-key: ps_your_key_here" \
  -d '{
    "templateId": "onboarding-test",
    "destinationNumber": "+5511999999999",
    "variables": { "name": "John", "order_id": "123" }
  }'

curl -X POST "https://pilotstatus.com.br/v1/messages/send" \
  -H "Content-Type: application/json" \
  -H "x-api-key: ps_your_key_here" \
  -d '{
    "templateId": "onboarding-test",
    "destinationNumber": "+5511999999999",
    "variables": { "name": "John" },
    "labels": ["vip", "customers"],
    "deliverAt": "2026-02-24T15:05:00.000Z"
  }'

curl -X POST "https://pilotstatus.com.br/v1/messages/send" \
  -H "Content-Type: application/json" \
  -H "x-api-key: ps_your_key_here" \
  -d '{
    "text": "Hi! Your delivery has been confirmed for tomorrow.",
    "destinationNumber": "+5511999999999"
  }'

curl -X POST "https://pilotstatus.com.br/v1/messages/send" \
  -H "Content-Type: application/json" \
  -H "x-api-key: ps_your_key_here" \
  -d '{
    "text": "Would you like to confirm your appointment?",
    "destinationNumber": "+5511999999999",
    "buttons": [
      { "type": "reply", "displayText": "Confirm", "id": "confirm" },
      { "type": "reply", "displayText": "Cancel", "id": "cancel" }
    ]
  }'

curl -X POST "https://pilotstatus.com.br/v1/messages/send" \
  -H "Content-Type: application/json" \
  -H "x-api-key: ps_your_key_here" \
  -d '{
    "text": "Your reservation is confirmed!",
    "destinationNumber": "+5511999999999",
    "header": { "type": "image", "content": "https://example.com/reservation.png" },
    "footer": "Example Hotel",
    "buttons": [
      { "type": "url", "displayText": "View details", "url": "https://example.com/reservation/123" }
    ]
  }'

curl -X POST "https://pilotstatus.com.br/v1/messages/send" \
  -H "Content-Type: application/json" \
  -H "x-api-key: ps_your_key_here" \
  -d '{
    "destinationNumber": "+5511999999999",
    "media": "https://cdn.example.com/voice.ogg",
    "mediaType": "audio"
  }'

curl -X POST "https://pilotstatus.com.br/v1/messages/send" \
  -H "Content-Type: application/json" \
  -H "x-api-key: ps_your_key_here" \
  -d '{
    "destinationNumber": "+5511999999999",
    "media": "data:image/png;base64,iVBORw0...",
    "mediaType": "image"
  }'

curl -X POST "https://pilotstatus.com.br/v1/messages/send" \
  -H "Content-Type: application/json" \
  -H "x-api-key: ps_your_key_here" \
  -d '{
    "templateId": "confirm-template",
    "destinationNumber": "+5511999999999",
    "variables": { "name": "John" },
    "media": "https://example.com/promo.png",
    "mediaType": "image",
    "buttons": [
      { "type": "reply", "displayText": "Yes", "id": "confirm" },
      { "type": "url", "displayText": "View offer", "url": "https://example.com/offer" }
    ]
  }'

Response (202)

{
  "id": "msg_abc",
  "correlationId": "corr_123",
  "status": "QUEUED",
  "createdAt": "2026-02-24T15:00:00.000Z",
  "origin": "My WhatsApp"
}

string

Internal message ID. Persist this — it is the value to use with GET /v1/messages/{id} and it matches internalMessageId in webhooks.

string

Correlation identifier for the send request.

string

Always QUEUED on accept.

Correlation with webhooks

The id field in the response is the same as the id field in message.sent, message.delivered, message.read, and message.failed. On message.reply, use quotedMessageId (the WhatsApp messageId of your original message) and correlationId to tie the reply to your send.
The WhatsApp messageId (wamid) is not in the 202 body; it first appears on the message.sent webhook (and repeats on status events for that message).
Persist id when you receive 202 and use GET /v1/messages/{id} with the same value.

Common errors

Status	Meaning
`400`	Invalid payload (e.g., phone not in E.164, missing required fields, `MISSING_TEMPLATE_VARIABLES`, or free-form not supported by the provider: `code: FREE_FORM_NOT_SUPPORTED`)
`401`	Missing/invalid API key header (`x-api-key` / `x-api-key-id`)
`403`	A tenant-scoped key used on a number-scoped endpoint
`404`	Template not found or without an approved version
`422`	Tenant billing is suspended (`code: BILLING_SUSPENDED`) — dunning, or an unpaid WALLET / extras balance; regularize your credits or card to resume sending
`429`	Rate limit

Asynchronous delivery failures (e.g. META_OUTSIDE_24H_WINDOW, META_TEMPLATE_NOT_APPROVED, WHATSAPP_NOT_EXIST) surface via the message.failed webhook and in Logs — see Log Error Codes.

Overview

Messaging

Templates

Numbers

Conversations & Data

Webhooks

Voice Calls

API Layer

Account & Billing

Branding & Embedding

POST /v1/messages/send — Send a WhatsApp Message

Send a WhatsApp Message

Headers

Destination (exactly one)

Mode fields

Direct media send

Scheduling and delivery window

Other fields

Free-form restrictions

Buttons

Lists

Examples

Response (202)

Correlation with webhooks

Common errors

​Send a WhatsApp Message

​Headers

​Destination (exactly one)

​Mode fields

​Direct media send

​Scheduling and delivery window

​Other fields

​Free-form restrictions

​Buttons

​Lists

​Examples

​Response (202)

​Correlation with webhooks

​Common errors

Send a WhatsApp Message

Headers

Destination (exactly one)

Mode fields

Direct media send

Scheduling and delivery window

Other fields

Free-form restrictions

Buttons

Lists

Examples

Response (202)

Correlation with webhooks

Common errors