---
name: whatsapp-platform
description: Integra o Exerion Zap, uma API multi-tenant sobre a WhatsApp Cloud API oficial da Meta. Use quando o pedido for conectar o WhatsApp de um cliente por um link, enviar ou receber mensagens do WhatsApp, criar ou enviar templates, ou tratar os webhooks e eventos de conexão.
---

# Exerion Zap

Uma **conta** (quem integra) tem **customers** (os clientes dela, por exemplo um restaurante); cada customer conecta o próprio número de WhatsApp por um **link** e o número vira uma **connection**. Você envia mensagens por uma connection e recebe os eventos por **webhook**.

## Regras que valem sempre

1. **A API key vem do ambiente.** A URL da API está em `WHATSAPP_PLATFORM_API_URL` e a chave em `WHATSAPP_PLATFORM_API_KEY`; toda chamada leva `Authorization: Bearer $WHATSAPP_PLATFORM_API_KEY`. Nunca escreva a chave em arquivo versionado, log, comentário ou conversa. Se a variável não existir, pare e peça ao humano.
2. **Sem `Content-Type: application/json` em requisição sem corpo** (a API a recusa).
3. **Quem conecta o número é o cliente, no navegador, com o login dele na Meta.** Você gera o link e o entrega; não tente automatizar o fluxo da Meta.
4. **A verdade sobre uma conexão é o webhook `whatsapp.connection.created`** (ou `GET /v1/customers/{id}`), não o navegador nem o redirecionamento do link.
5. **Valide a assinatura dos webhooks** (`X-WhatsApp-Platform-Signature`, HMAC-SHA256 do corpo bruto) antes de confiar neles.
6. **Confirme antes de fazer algo que fala com um cliente de verdade:** enviar mensagens, mandar links e apagar templates são ações visíveis para pessoas.
7. **Dado pessoal (LGPD):** o telefone ou o BSUID de um contato vai no corpo da requisição, nunca na URL, e nunca em log. Encerrar a conta e aceitar os termos são de uma pessoa: não os faça. Ver [privacidade](references/privacy.md).

## Fluxo

1. Confirme que as variáveis de ambiente existem, sem imprimir os valores.
2. Tenha um customer: `POST /v1/customers/default` (o do próprio dono da conta) ou `POST /v1/customers`.
3. Gere o link: `POST /v1/customers/{id}/signup_links` e entregue a `url` ao cliente. Detalhes (tipos de conexão, idioma, redirecionamentos, embutir no seu app) em [conectar um número](references/connect-a-number.md).
4. Espere `whatsapp.connection.created`, ou consulte `GET /v1/customers/{id}` até a conexão ficar `CONNECTED`.
5. Envie mensagens com `POST /v1/connections/{id}/messages`. Texto livre só vai dentro de 24 horas depois da última mensagem do contato; fora disso, use um template. Ver [enviar mensagens](references/send-messages.md) e [templates](references/templates.md).
6. Receba mensagens e eventos: cadastre a URL com `POST /v1/webhook-endpoints` e trate os eventos. Ver [webhooks](references/webhooks.md).
7. Ao terminar, resuma o que foi criado (arquivos, variáveis de ambiente, rotas usadas) e o que ficou pendente.

## Onde ler mais (leia só o que a tarefa pedir)

- [references/connect-a-number.md](references/connect-a-number.md): links de conexão, dedicado ou coexistência, o cliente escolher, reconexão e número que perdeu o acesso.
- [references/send-messages.md](references/send-messages.md): o corpo do envio, a janela de 24 horas, BSUID, origem e preço das mensagens.
- [references/templates.md](references/templates.md): criar, sincronizar, apagar e enviar templates, e o resultado da análise da Meta.
- [references/webhooks.md](references/webhooks.md): os eventos, a assinatura, o reenvio e como depurar um endpoint.
- [references/embed.md](references/embed.md): mostrar a conexão dentro do app da conta, com as origens permitidas e o SDK.
- [references/inbox.md](references/inbox.md): as conversas, responder com a regra das 24 horas e o inbox dentro do app da conta.
- [references/privacy.md](references/privacy.md): a LGPD: por quanto tempo as mensagens são guardadas, atender o pedido de um titular (baixar e apagar os dados de um contato) e os dados da própria conta.

O contrato completo, em um arquivo só, está em `/llms-full.txt` no painel; a lista das rotas, em `/docs`.