Pular para o conteúdo principal
Para receber mensagens recebidas do WhatsApp e eventos de entrega em tempo real, registre um webhook: um endpoint HTTPS no seu sistema que o Pilot Status chama com um POST JSON para cada evento.

​
Criar um webhook

Acesse a página Webhooks (/webhooks) no dashboard, clique em New Webhook, informe sua URL e escolha os eventos desejados. Os webhooks têm escopo por número.
O controle de eventos é explícito: uma lista events vazia não dispara nada — não existe uma inscrição implícita em “todos”. Use "*" para receber todos os eventos. No PATCH, events substitui a lista inteira (sem merge), e o número do webhook não pode ser alterado após a criação.
Para pausar as entregas sem excluir, faça um PATCH com { "active": false }. O secret de assinatura nunca é retornado por nenhum endpoint.

​
Exemplo de payload — message.received

{
  "event": "message.received",
  "data": {
    "from": "+5511999999999",
    "to": "+5511888888888",
    "numberId": "cmm0abc123",
    "messageId": "msg_in_id",
    "id": "cmm04obm46zz0qv4ycjp8x6r2",
    "type": "text",
    "fromMe": false,
    "content": "Hi",
    "participantName": "WhatsApp name",
    "createdAt": "2026-02-24T10:30:00.000Z"
  }
}
Para mensagens de mídia, mediaLink, mediaType, mediaCaption e mediaFilename aparecem quando o provedor os expõe (por exemplo, Meta Cloud API). Consulte a Referência de eventos para todos os eventos e campos.

​
Exemplos de receptor

Retorne 200 rapidamente e processe o evento de forma assíncrona; deduplique por data.id, já que as retentativas podem entregar um evento mais de uma vez. 
import express from "express";

const app = express();
app.use(express.json());

app.post("/hooks/whatsapp", (req, res) => {
  const { event, data } = req.body;

  // Acknowledge immediately, process async
  res.sendStatus(200);

  if (event === "message.received") {
    console.log(`Message from ${data.from}: ${data.content}`);
    // enqueue reply, run your bot, etc.
  }
});

app.listen(3000);

​
Respondendo a uma mensagem recebida

Responda com POST /v1/messages/send usando o número do remetente como destino: 
curl -X POST "https://pilotstatus.com.br/v1/messages/send" \
  -H "x-api-key: ps_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "text": "Thanks, we got your message!", "destinationNumber": "+5511999999999" }'
message.reply é disparado quando um contato cita uma das suas mensagens — use quotedMessageId para relacioná-lo ao messageId do seu message.sent original. message.read só é disparado quando o destinatário tem as confirmações de leitura habilitadas.

​
Relacionados