Skip to main content

​
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:
  1. Template send — templateId (+ optional variables)
  2. Free-form text send — text
  3. 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

​
Headers

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

​
Destination (exactly one)

​
destinationNumber
string
Destination phone in E.164 with a leading + (e.g., +5511999999999).
​
groupId
string
WhatsApp group JID ending in @g.us.
​
newsletterId
string
WhatsApp channel JID ending in @newsletter.

​
Mode fields

​
templateId
string
Template from the dashboard /templates. Mutually exclusive with text and direct-media mode.
​
variables
object
Key→value map for template variables. Missing required variables produce MISSING_TEMPLATE_VARIABLES.
​
text
string
Body of a free-form message. Required if templateId is not sent (and not doing a direct media send).
​
media
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.
​
mediaType
string
image, video, document, or audio. 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. On unofficial (Pilot Status web) numbers a “recording audio” presence indicator is shown just before delivery; Meta Cloud API has no outbound presence API, so no indicator is shown for Meta audio sends.

​
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.
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

​
deliverAt
string
ISO 8601 datetime to schedule the send.
​
deliverUntil
string
ISO 8601 deadline for delivery. If it expires, the message fails (see Log Error Codes).

​
Other fields

​
labels
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).
​
marketingOptions
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.
​
buttons
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.
​
header
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.
​
footer
string
Message footer (max 60 characters). Requires buttons.

​
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.

​
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" }
  }'

​
Response (202)

{
  "id": "msg_abc",
  "correlationId": "corr_123",
  "status": "QUEUED",
  "createdAt": "2026-02-24T15:00:00.000Z",
  "origin": "My WhatsApp"
}
​
id
string
Internal message ID. Persist this — it is the value to use with GET /v1/messages/{id} and it matches internalMessageId in webhooks.
​
correlationId
string
Correlation identifier for the send request.
​
status
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

StatusMeaning
400Invalid 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)
401Missing/invalid API key header (x-api-key / x-api-key-id)
403A tenant-scoped key used on a number-scoped endpoint
404Template not found or without an approved version
422Tenant billing is suspended (code: BILLING_SUSPENDED) — dunning, or an unpaid WALLET / extras balance; regularize your credits or card to resume sending
429Rate 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.