Documentação do wapit

O wapit é uma WhatsApp Cloud API local para desenvolvimento: o Mailpit do WhatsApp. Aponte a URL base da Graph API do seu app para o wapit, mantenha o código de verdade e veja cada mensagem numa caixa de entrada local com cara de conversa. Ele não tem vínculo com a Meta nem com o WhatsApp.

Com o Homebrew, no macOS ou no Linux:

$ brew install patriciomartinns/tap/wapit

Ou rode o container. As duas últimas opções deixam o wapit entregar webhooks a apps na sua máquina, como http://localhost:8000, de dentro do container:

$ docker run --rm -p 127.0.0.1:8026:8026 -p 127.0.0.1:8027:8027 \
  --add-host host.docker.internal:host-gateway \
  -e WAPIT_LOOPBACK_HOST=host.docker.internal \
  ghcr.io/patriciomartinns/wapit

Ou compile a partir do código, com Rust 1.89 ou mais novo:

$ cargo install --locked --git https://github.com/patriciomartinns/wapit

No Windows, baixe wapit-<versão>-x86_64-pc-windows-msvc.zip da release mais recente, descompacte e rode wapit.exe. A mesma página tem os binários prontos para macOS e Linux e um arquivo SHA256SUMS para conferir cada um: github.com/patriciomartinns/wapit/releases/latest

Rode wapit sem configuração nenhuma e ele serve um app padrão. A caixa de entrada fica em http://127.0.0.1:8026 e a Graph API em http://127.0.0.1:8027.

Use os mesmos valores no seu app, com http://127.0.0.1:8027 como URL base da Graph API, e mande uma mensagem:

$ curl http://127.0.0.1:8027/v26.0/100000000000001/messages \
  -H 'Authorization: Bearer wapit-local-token' \
  -H 'Content-Type: application/json' \
  -d '{"messaging_product":"whatsapp","to":"15550000000","type":"text","text":{"body":"Hello"}}'

Uma mensagem livre para quem nunca falou com você é aceita e depois falha com o erro 131047, igual à Meta fora da janela de atendimento de 24 horas. Responda como o usuário pela caixa de entrada para abrir a janela.

O wapit aceita qualquer versão no caminho, ou nenhuma. Os exemplos usam a v26.0, a versão estável mais recente da Graph API, e os webhooks têm o formato da v24.0 em diante, sem o objeto conversation nos status.

Copie config/apps.example.json para config/apps.json e descreva seus apps. Cada app é um número de WhatsApp:

O arquivo recarrega quando muda. Se uma edição quebrar o arquivo, o wapit mantém a última versão boa e mostra o erro na caixa de entrada.

Os templates ficam em config/templates/<id do app>.json, no formato que o endpoint message_templates da Meta devolve. O seu app também pode criar, editar e apagar templates pela Graph API, e eles são aprovados na hora.

Copie os templates da sua conta real, só para leitura, com:

$ WAPIT_SYNC_TOKEN=... wapit sync <id do app>

Ele lê a Graph API v26.0, a menos que sync.graph_version do app diga outra versão. Os templates sincronizados mantêm os ids da Meta, então POST /{template_id} e hsm_id usam os mesmos ids da sua conta real. É o único comando que fala com a Meta, e só quando você roda.

Um app rodando em outro container precisa chegar ao wapit por um nome que resolva lá, como host.docker.internal:8027. As URLs de mídia seguem WAPIT_PUBLIC_API_URL, então use esse mesmo endereço nela.

Uma reação só recebe o status sent, como na Meta, e uma reação a uma mensagem que não está na conversa, que também é uma reação ou que tem mais de 30 dias é aceita e depois falha com o erro 131009.

Envie com recipient preenchido com um ID de usuário por empresa (BSUID), como US.13491208655302741918, no lugar de to, e a resposta identifica o contato como user_id em vez de wa_id. Quando um envio traz os dois, vale o to, como na Meta. Os webhooks seguem o formato que a Meta usa desde abril de 2026: contacts[].user_id, messages[].from_user_id e statuses[].recipient_user_id vêm sempre, e wa_id, from e recipient_id só nas conversas com número de telefone. O wapit deriva um BSUID estável para cada número a partir do número e do id da conta do WhatsApp Business. Um envio cujo recipient é esse BSUID derivado vai para a conversa do número, dentro da janela de atendimento dela. Templates de autenticação de um toque, sem toque e de copiar código não podem ir para um BSUID (131062). Destinatários de grupo (recipient_type: group) não são suportados.

Os envios são conferidos como a Meta confere. Um envio rejeitado devolve o erro da Meta ao seu app e fica na caixa de entrada, marcado, com o motivo em palavras simples.

Numa conversa você pode digitar uma mensagem, anexar um arquivo, tocar num botão de resposta, de resposta rápida ou de lista, ou escolher uma mensagem do seu app para marcar como entregue, lida, ouvida (só mensagens de voz) ou falha, com um código de erro real da Meta. Cada ação vai para o webhook do app no formato de payload da Meta, assinada com o app secret em X-Hub-Signature-256. Como na Meta, o objeto de preço vem com o status sent e com o primeiro entre delivered e read, nunca com os dois.

O inspetor mostra o payload que o seu app enviou, cada entrega de webhook com a resposta do app, e permite enviar um webhook de novo. Apps com verify_token também podem rodar a verificação da assinatura pela caixa de entrada.

O wapit entrega cada webhook uma vez só. Ao contrário da Meta, que reenvia uma entrega que falhou, ele não reenvia sozinho: se o seu app estiver fora do ar ou responder com erro, a entrega fica marcada como falha no inspetor e você envia de novo por lá.

O wapit não tem autenticação, de propósito: é uma ferramenta de desenvolvimento para a sua máquina.

• Ele escuta em 127.0.0.1.
• Só atende requisições cujo Host é um nome local, então uma página da web não chega nele por DNS rebinding.
• A Graph API recusa escritas que trazem o Origin de um navegador, então uma página que você visita não consegue mandar mensagens por ele com o token padrão.

Não exponha as portas dele para fora da sua máquina. Relate vulnerabilidades em particular pelo GitHub: github.com/patriciomartinns/wapit/security