Send Messages Guide

This guide shows how to send WhatsApp messages via the Pilot Status API. All sends go through a single endpoint:

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

Authentication uses the x-api-key: ps_... header (or x-api-key-id) with a number-scoped key — see API Authentication. There is no Bearer-token auth.

Sending from the dashboard Message page — You can also send from the dashboard Message page — it calls the same POST /v1/messages/send endpoint and shows a copy-ready curl.

The endpoint has three mutually exclusive modes: template send (templateId), free-form text (text), and direct media (media + mediaType). Full reference: POST /v1/messages/send.

Prerequisites

A connected WhatsApp number (dashboard /numbers).
An API key for that number (dashboard /api-keys).
For template sends: a template created in /templates (Meta numbers require Meta approval).

1. Send a template message

The most reliable mode — works at any time, including outside the 24h window on Meta numbers.

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

const res = await fetch("https://pilotstatus.com.br/v1/messages/send", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-api-key": process.env.PILOT_STATUS_API_KEY, // ps_...
  },
  body: JSON.stringify({
    templateId: "onboarding-test",
    destinationNumber: "+5511999999999",
    variables: { name: "John", order_id: "123" },
  }),
});

const data = await res.json(); // 202 => { id, correlationId, status: "QUEUED", ... }
console.log(data.id); // persist this to track delivery

2. Send free-form text

Send plain text with the text field (no templateId).

On Meta numbers, free-form messages only work within the WhatsApp 24h conversation window (i.e. after the recipient messaged you in the last 24 hours). Outside the window, the send fails asynchronously with META_OUTSIDE_24H_WINDOW in the message.failed webhook — use an approved template instead. Check whether the window is open before sending with GET /v1/service-window.

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

await fetch("https://pilotstatus.com.br/v1/messages/send", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-api-key": process.env.PILOT_STATUS_API_KEY,
  },
  body: JSON.stringify({
    text: "Hi! Your delivery has been confirmed for tomorrow.",
    destinationNumber: "+5511999999999",
  }),
});

You can add up to 3 buttons (and, with buttons, a header/footer) to free-form messages — see the send reference.

3. Send direct media

Send an image, video, document, or audio on its own — provide media + mediaType, with no templateId and no text. An optional caption is allowed for image/video/document (not audio). mediaType: "audio" is delivered as a WhatsApp voice note (PTT).

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

await fetch("https://pilotstatus.com.br/v1/messages/send", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-api-key": process.env.PILOT_STATUS_API_KEY,
  },
  body: JSON.stringify({
    destinationNumber: "+5511999999999",
    media: "https://cdn.example.com/report.pdf",
    mediaType: "document",
    caption: "Your monthly report",
  }),
});

Base64 data URIs are accepted on Meta Cloud API numbers; unofficial (Pilot Status web) numbers require a public http(s) URL.

4. Track delivery

The 202 response returns an id. Persist it and:

Poll GET /v1/messages/{id} for QUEUED → SENT → DELIVERED → READ (or FAILED / CANCELED), or
Consume webhooks — the response id matches the id field in the message.sent, message.delivered, message.read, and message.failed events.

Next steps

Full field reference and error codes: POST /v1/messages/send
Scheduling with deliverAt and canceling: DELETE /v1/messages/cancel
Failure diagnostics: Log Error Codes

Get Started

Core Concepts

Guides

Integrations

Dashboard

Trust & Data

Plans & Support

Changelog

Send WhatsApp Messages via API | Pilot Status

Send Messages Guide

Prerequisites

1. Send a template message

2. Send free-form text

3. Send direct media

4. Track delivery

Next steps

​Send Messages Guide

​Prerequisites

​1. Send a template message

​2. Send free-form text

​3. Send direct media

​4. Track delivery

​Next steps

Send Messages Guide

Prerequisites

1. Send a template message

2. Send free-form text

3. Send direct media

4. Track delivery

Next steps