Documentação
API do Exerion Zap
Uma API sobre a WhatsApp Cloud API oficial da Meta. Cada cliente seu conecta o próprio número por um link, e você envia e recebe mensagens, gerencia templates e recebe eventos por webhook.
Como autenticar
Toda rota leva Authorization: Bearer <API key>. Crie a chave em API keys e guarde-a no ambiente do seu servidor (nunca em código versionado, em log ou em uma conversa). Respostas em JSON; não envie Content-Type: application/json em uma requisição sem corpo.
Para agentes de código e modelos
- /llms.txt: o índice para modelos de linguagem.
- /llms-full.txt: o contrato completo em um arquivo só.
- /skills/whatsapp-platform/SKILL.md: uma skill (formato SKILL.md) com referências que se leem só quando preciso.
- Quick setup: o passo a passo, com o prompt pronto para colar no seu agente.
Rotas
Customers
| Método | Caminho | O que faz |
|---|---|---|
| POST | /v1/customers/default | Cria (ou devolve) o customer padrão da conta, para conectar o seu próprio número. |
| POST | /v1/customers | Cria um customer: um tenant seu, com o seu identificador (externalId). |
| GET | /v1/customers | Lista os customers da conta. |
| GET | /v1/customers/{id} | Um customer com as suas conexões e o status de cada uma. |
Setup links
| Método | Caminho | O que faz |
|---|---|---|
| POST | /v1/customers/{id}/signup_links | Gera o link para o cliente conectar o número (tipo, idioma, redirecionamentos, origens que podem embutir a página). |
| GET | /v1/setup_links | Lista os links da conta, com filtros por status e customer. |
| GET | /v1/customers/{id}/setup_links | Lista os links de um customer. |
| PATCH | /v1/setup_links/{id} | Revoga um link ativo ou muda o prazo, o idioma, os redirecionamentos e as origens. |
| POST | /v1/connections/{id}/reconnect_links | Gera o link para o cliente reconectar um número que perdeu o acesso. |
Conexões e mensagens
| Método | Caminho | O que faz |
|---|---|---|
| GET | /v1/connections/{id} | Uma conexão: número, status, tipo e qualidade (nunca segredos). |
| POST | /v1/connections/{id}/messages | Envia uma mensagem (texto, template, mídia ou interativa) por número ou por BSUID. |
| GET | /v1/connections/{id}/messages | As últimas 100 mensagens da conexão, com origem, status e preço da Meta. |
| POST | /v1/connections/{id}/rotate_pin | Troca o PIN de registro de um número registrado pela plataforma. |
Templates
| Método | Caminho | O que faz |
|---|---|---|
| GET | /v1/connections/{id}/templates | Os templates do número (a cópia sincronizada), com o status da análise da Meta. |
| POST | /v1/connections/{id}/templates/sync | Lê os templates da Meta e atualiza a cópia. |
| POST | /v1/connections/{id}/templates | Envia um template novo para a análise da Meta. |
| DELETE | /v1/connections/{id}/templates/{templateId} | Apaga um template (só aquele idioma) na Meta e aqui. |
Inbox
| Método | Caminho | O que faz |
|---|---|---|
| GET | /v1/conversations | As conversas dos seus números, da mais recente à mais antiga, com o que não foi lido e se a janela de 24 horas está aberta. |
| GET | /v1/conversations/{id}/messages | As mensagens de uma conversa. |
| POST | /v1/conversations/{id}/read | Marca a conversa como lida. |
| POST | /v1/conversations/{id}/messages | Responde ao contato: texto com a janela aberta, template a qualquer hora. |
| GET | /v1/conversations/{id}/templates | Os templates aprovados da conexão da conversa. |
| POST | /v1/inbox/tokens | Gera um token de vida curta para mostrar o inbox dentro do seu app. |
Webhooks
| Método | Caminho | O que faz |
|---|---|---|
| POST | /v1/webhook-endpoints | Cadastra ou troca a URL que recebe os eventos. |
| GET | /v1/webhook-endpoints | A URL cadastrada e o segredo de assinatura. |
| POST | /v1/webhook-endpoints/rotate-secret | Gera outro segredo de assinatura (o atual deixa de valer na hora). |
| GET | /v1/webhook-endpoints/{id}/deliveries | As tentativas de entrega de eventos, com filtros. |
| GET | /v1/webhook-endpoints/{id}/deliveries/event-types | Os tipos de evento que já foram entregues (para filtrar). |
| GET | /v1/webhook-endpoints/{id}/deliveries/{deliveryId} | Uma entrega com o corpo enviado e a resposta do seu endpoint. |
| POST | /v1/webhook-endpoints/{id}/deliveries/{deliveryId}/redeliver | Reenvia o mesmo evento como uma entrega nova. |
Conta, uso e chaves
| Método | Caminho | O que faz |
|---|---|---|
| GET | /v1/me | A conta que a credencial representa. |
| PATCH | /v1/me | Corrige o nome ou o e-mail da conta (o e-mail pede a senha; só com sessão do painel, não com API key). |
| GET | /v1/accounts/{id} | Os dados da própria conta. |
| GET | /v1/usage | O que a conta usou no ciclo contra o que o plano inclui. |
| GET | /v1/analytics/messages | Mensagens por período, status, direção, tipo, customer e preço da Meta. |
| GET | /v1/logs | Os logs da conta numa lista só: a sua API, as chamadas à Meta, os avisos da Meta e as entregas de webhook. |
| GET | /v1/brand | Nome, logo e cores da página de conexão. |
| PATCH | /v1/brand | Muda o nome, o logo e as cores da página de conexão. |
| POST | /v1/api-keys | Cria uma API key (o valor aparece uma vez). |
| GET | /v1/api-keys | Lista as API keys (sem o valor). |
| DELETE | /v1/api-keys/{id} | Revoga uma API key. |
Privacidade (LGPD)
| Método | Caminho | O que faz |
|---|---|---|
| GET | /v1/privacy | O aceite dos Termos e da Política e por quanto tempo cada tipo de dado é guardado. |
| PATCH | /v1/privacy/settings | Escolhe por quantos dias o conteúdo das mensagens é guardado (30 a 1825; null volta ao padrão). |
| GET | /v1/privacy/export | Os dados da própria conta para levar (sem senha, hashes, tokens nem segredos). |
| POST | /v1/privacy/contacts/export | Todas as mensagens da conta com um contato (telefone ou BSUID no corpo), para responder a um titular. |
| POST | /v1/privacy/contacts/erase | Tira o número, o BSUID e o conteúdo de um contato das mensagens, das cópias de eventos e do inbox. |
| POST | /v1/privacy/contacts/block | Bloqueia um contato (art. 18, IV): suspende o tratamento e mantém o dado; nada é recebido, repassado nem enviado para ele. |
| POST | /v1/privacy/contacts/unblock | Retira o bloqueio de um contato (pelo contato, ou pelo id do bloqueio). |
| GET | /v1/privacy/contacts/blocked | Os contatos bloqueados, com o número ou o id só pelo final. |
| POST | /v1/privacy/accept-terms | Registra o aceite dos Termos e da Política em vigor (só com sessão do painel). |
| POST | /v1/privacy/account/block | Bloqueia a conta a pedido do titular: fecha as sessões e as chaves, suspende o tratamento e mantém o dado. Só sessão do painel; só o Encarregado reativa. |
| POST | /v1/privacy/account/erase | Encerra a conta e apaga tudo nela. Irreversível; pede a senha e só aceita sessão do painel. |
Eventos de webhook
Cada evento chega por POST na sua URL, com o corpo { "type": "...", "data": { ... } } e o cabeçalho X-WhatsApp-Platform-Signature (HMAC-SHA256 do corpo bruto). Confirme uma conexão por whatsapp.connection.created, não pelo navegador.
| Evento | Quando |
|---|---|
| whatsapp.messages | Mensagem recebida ou status de entrega de uma enviada (o objeto da Meta). |
| whatsapp.connection.created | O cliente conectou um número. |
| whatsapp.connection.reconnected | Um número perdido voltou (reconexão ou, em coexistência, a Meta avisou que voltou). |
| whatsapp.connection.needs_reattention | A Meta recusou a autorização do cliente ou o número saiu do aplicativo: gere um link de reconexão. |
| whatsapp.connection.disconnected | O cliente removeu o acesso da plataforma: gere um link de reconexão. |
| whatsapp.smb_message_echoes | O que o cliente escreveu no aplicativo, em um número com coexistência. |
| whatsapp.smb_app_state_sync | Contatos do aplicativo (coexistência), repassados como a Meta os manda. |
| whatsapp.setup_link.expired | Um link de conexão venceu sem ser usado. |
| whatsapp.message_template_status_update | A Meta aprovou, rejeitou, pausou ou apagou um template. |
| whatsapp.message_template_quality_update | A qualidade de um template mudou. |
| whatsapp.template_category_update | A categoria de um template mudou. |