Receba mensagens do WhatsApp e eventos de entrega via webhooks

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

Dashboard
API

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.

curl -X POST "https://pilotstatus.com.br/v1/webhooks" \
  -H "x-api-key: ps_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/hooks/whatsapp",
    "name": "My hook",
    "events": ["message.received", "message.sent", "message.delivered"]
  }'

O CRUD completo está disponível: GET /v1/webhooks, GET/PATCH/DELETE /v1/webhooks/{id} e GET /v1/webhooks/{id}/logs para as tentativas de entrega recentes. Com uma chave de escopo de número, o webhook é associado ao número dessa chave; com uma chave de escopo de tenant, passe whatsappNumberId no corpo (ou o header x-whatsapp-number-id).

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 — para validar as entregas com ele, veja Verifique a assinatura.

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 é uma URL pública e durável para a mídia re-hospedada no armazenamento do Pilot Status — para todos os provedores (Evolution GO, Evolution v2, Meta Cloud API), incluindo mídia criptografada de ponta a ponta do WhatsApp descriptografada no servidor — junto de mediaType, mediaCaption e mediaFilename. 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);

from flask import Flask, request

app = Flask(__name__)

@app.post("/hooks/whatsapp")
def whatsapp_hook():
    payload = request.get_json()
    event = payload.get("event")
    data = payload.get("data", {})

    if event == "message.received":
        print(f"Message from {data.get('from')}: {data.get('content')}")
        # enqueue reply, run your bot, etc.

    return "", 200

if __name__ == "__main__":
    app.run(port=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.

Primeiros Passos

Conceitos

Guias

Integrações

Painel

Confiança & Dados

Planos & Suporte

Changelog

Receba mensagens do WhatsApp e eventos de entrega via webhooks

Criar um webhook

Exemplo de payload — `message.received`

Exemplos de receptor

Respondendo a uma mensagem recebida

Relacionados

​Criar um webhook

​Exemplo de payload — message.received

​Exemplos de receptor

​Respondendo a uma mensagem recebida

​Relacionados

Criar um webhook

Exemplo de payload — `message.received`

Exemplos de receptor

Respondendo a uma mensagem recebida

Relacionados