Guia de envio de mensagens

Este guia mostra como enviar mensagens de WhatsApp pela API do Pilot Status. Todos os envios passam por um único endpoint:

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

A autenticação usa o cabeçalho x-api-key: ps_... (ou x-api-key-id) com uma chave com escopo de número — veja Autenticação da API. Não há autenticação por Bearer-token.

Envio pela página Mensagem do painel — Você também pode enviar pela página Mensagem do painel — ela chama o mesmo endpoint POST /v1/messages/send e mostra um curl pronto para copiar.

O endpoint tem três modos mutuamente exclusivos: envio de template (templateId), texto livre (text) e mídia direta (media + mediaType). Referência completa: POST /v1/messages/send.

Pré-requisitos

Um número de WhatsApp conectado (painel /numbers).
Uma chave de API para esse número (painel /api-keys).
Para envios de template: um template criado em /templates (números Meta exigem aprovação da Meta).

1. Enviar uma mensagem de template

O modo mais confiável — funciona a qualquer momento, inclusive fora da janela de 24h em números Meta.

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. Enviar texto livre

Envie texto simples com o campo text (sem templateId).

Em números Meta, mensagens de texto livre só funcionam dentro da janela de conversa de 24h do WhatsApp (ou seja, após o destinatário ter enviado mensagem para você nas últimas 24 horas). Fora da janela, o envio falha de forma assíncrona com META_OUTSIDE_24H_WINDOW no webhook message.failed — use um template aprovado em vez disso. Verifique se a janela está aberta antes de enviar com 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",
  }),
});

Você pode adicionar até 3 buttons (e, com botões, um header/footer) às mensagens de texto livre — veja a referência de envio.

3. Enviar mídia direta

Envie uma imagem, vídeo, documento ou áudio isoladamente — forneça media + mediaType, sem templateId e sem text. Um caption opcional é suportado para imagem/vídeo/documento (não para áudio nem nota de voz). Use mediaType: "voice" para uma nota de voz (PTT) do WhatsApp em qualquer número; mediaType: "audio" chega como arquivo de áudio em números oficiais (Meta Cloud API) e como nota de voz em números não oficiais — veja Áudio e nota de voz.

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

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",
  }),
});

URIs de dados Base64 são aceitos em números Meta Cloud API e em números não oficiais (Pilot Status web). Em números não oficiais, a Pilot Status sobe o arquivo decodificado para o próprio armazenamento e envia uma URL ao provedor; se esse upload falhar, a mensagem falha com MEDIA_REHOST_FAILED. Para figurinhas em números não oficiais, use uma URL http(s) pública. O base64 vai até 50 MiB decodificados para document e 16 MiB para os demais tipos — envie arquivos maiores por URL.

4. Acompanhar a entrega

A resposta 202 retorna um id. Persista-o e:

Consulte GET /v1/messages/{id} para QUEUED → SENT → DELIVERED → READ → PLAYED (ou FAILED / CANCELED), ou
Consuma webhooks — o id da resposta corresponde ao campo id nos eventos message.sent, message.delivered, message.read e message.failed.

Próximos passos

Referência completa de campos e códigos de erro: POST /v1/messages/send
Agendamento com deliverAt e cancelamento: DELETE /v1/messages/cancel
Diagnóstico de falhas: Códigos de erro de log

Primeiros Passos

Conceitos

Guias

Integrações

Painel

Confiança & Dados

Planos & Suporte

Changelog

Enviar mensagens de WhatsApp via API | Pilot Status

Guia de envio de mensagens

Pré-requisitos

1. Enviar uma mensagem de template

2. Enviar texto livre

3. Enviar mídia direta

4. Acompanhar a entrega

Próximos passos

​Guia de envio de mensagens

​Pré-requisitos

​1. Enviar uma mensagem de template

​2. Enviar texto livre

​3. Enviar mídia direta

​4. Acompanhar a entrega

​Próximos passos

Guia de envio de mensagens

Pré-requisitos

1. Enviar uma mensagem de template

2. Enviar texto livre

3. Enviar mídia direta

4. Acompanhar a entrega

Próximos passos