Pular para o conteúdo principal

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

  1. Um número de WhatsApp conectado (painel /numbers).
  2. Uma chave de API para esse número (painel /api-keys).
  3. 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" }
  }'

​
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.
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"
  }'
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 é permitido para imagem/vídeo/documento (não para áudio). mediaType: "audio" é entregue como uma nota de voz do WhatsApp (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"
  }'
URIs de dados Base64 são aceitos em números Meta Cloud API; números não oficiais (Pilot Status web) exigem uma URL http(s) pública.

​
4. Acompanhar a entrega

A resposta 202 retorna um id. Persista-o e:
  • Consulte GET /v1/messages/{id} para QUEUED → SENT → DELIVERED → READ (ou FAILED / CANCELED), ou
  • Consuma webhooks — o id da resposta corresponde ao internalMessageId em message.sent, message.delivered, message.read e message.failed.

​
Próximos passos