Pular para o conteúdo principal

​
Visão Geral da API Pilot Status

O Pilot Status é uma plataforma para envio de mensagens de WhatsApp (transacionais e de marketing/em massa) com controle de templates, versionamento e visibilidade operacional via painel, API e webhooks.

​
Base URL

https://pilotstatus.com.br/v1

​
Autenticação

Toda requisição exige uma chave de API enviada no cabeçalho x-api-key (ou x-api-key-id com o ID da chave). As chaves usam o prefixo ps_.
A API não usa tokens Authorization: Bearer. Sempre autentique com o cabeçalho x-api-key: ps_... (ou x-api-key-id).
curl "https://pilotstatus.com.br/v1/messages/msg_abc" \
  -H "x-api-key: ps_your_key_here"
Página de API Keys do Pilot Status

​
Escopos de chave

EscopoVinculado aPode chamar
Escopo de número (padrão)Um número de WhatsAppTodos os endpoints de ação/dados desse número: POST /v1/messages/send, status de mensagem, cancelamento, grupos, newsletters, templates, analytics, mídia
Escopo de tenant (singleton)O tenant (sem número)Gerenciamento em nível de tenant: /v1/numbers/*, /v1/remote-pairing/*, /v1/api-keys, /v1/branding, /v1/webhooks/*, /v1/subscription/extra-numbers, /v1/billing/checkout e /v1/embed/sessions (superfície de conexão)
Consulte Autenticação da API para mais detalhes.

​
Conceitos principais

  • Template: um modelo de mensagem versionado referenciado por templateId nos envios via API. Para números Meta, os templates são submetidos à Meta para aprovação; para números não oficiais (Pilot Status web), eles são criados localmente sem etapa de aprovação.
  • Message: uma tentativa de envio criada por POST /v1/messages/send.
  • Webhooks: eventos de entrega (sent/delivered/read/failed) e mensagens recebidas (reply/received/group).
  • Confirmações de leitura: o status READ, o readAt e o webhook message.read só ocorrem quando o contato destinatário tem as confirmações de leitura do WhatsApp habilitadas.

​
Fluxo típico de integração

1

Criar templates

Crie templates no painel (/templates).
2

Conectar o WhatsApp

Configure seu número/instância de WhatsApp no painel (/profile e /numbers).
3

Criar uma chave de API

Crie uma chave de API na página /api-keys.
4

Enviar mensagens

Envie mensagens com POST /v1/messages/send.
5

Acompanhar a entrega

Consulte o status com GET /v1/messages/{messageId} e/ou consuma eventos via webhooks.

​
Erros HTTP comuns

StatusSignificado
400Payload inválido (ex.: telefone fora do formato E.164, campos obrigatórios ausentes)
401Cabeçalho x-api-key / x-api-key-id ausente ou inválido
403Chave válida, mas operação bloqueada (ex.: escopo de chave incorreto)
404Recurso não encontrado dentro do escopo da chave
429Limite de taxa excedido

​
Avisos (WhatsApp / antispam)

Envios em alto volume e não solicitados podem acionar os mecanismos antispam do WhatsApp (limites de taxa, bloqueios e banimentos). Você é responsável pelo opt-in/consentimento e pela conformidade com as leis aplicáveis e as políticas do WhatsApp.