API e webhooks¶
A API permite que outros sistemas (ERP, aplicativos, parceiros) enviem mensagens, consultem conversas, gerenciem contatos e abram tickets. Os webhooks avisam o seu sistema em tempo real.
| Item | Valor |
|---|---|
| Endereço | https://<domínio do painel>/api/v1 |
| Autenticação | Authorization: Bearer wak_... |
| Limite | 120 requisições por minuto por chave (ampliável para 300, 600 ou 1.200) e 60 envios por minuto por empresa |
| Erros | { "error": { "code": "...", "message": "...", "requestId": "..." } } |
A referência completa traz todos os endpoints, campos e exemplos.
1. Crie a chave (administrador)¶
Na tela API do painel:
- Clique em Nova chave e dê um nome que identifique a integração (ex.: "ERP - envio de faturas").
- Marque só as permissões necessárias. Acesso total pede confirmação e deve ficar restrito a integrações internas.
- Opcional: IPs permitidos (recomendado quando o servidor do integrador tem IP fixo), validade (30, 90, 180 dias, 1 ano ou sem validade) e limite de requisições.
- Copie a chave na hora: ela aparece uma única vez.
Na lista, cada chave mostra permissões, restrições, último uso (data e IP) e situação. Revogar corta o acesso imediatamente. Se uma chave aparecer onde não devia (chat, e-mail, print), revogue e crie outra.
| Permissão | Libera |
|---|---|
messages:send |
Enviar mensagens |
messages:read |
Consultar mensagens, mídias e conversas |
contacts:read / contacts:write |
Consultar / cadastrar e alterar contatos |
tickets:read / tickets:write |
Consultar / abrir tickets |
conversations:write |
Transferir e encerrar conversas |
webhooks:manage |
Cadastrar e remover webhooks |
* |
Acesso total |
2. Valide a chave¶
A resposta traz a empresa, as permissões da chave e o IP de onde a chamada saiu.
3. Envie uma mensagem¶
curl https://<domínio>/api/v1/messages \
-H "Authorization: Bearer $CHAVE" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: fatura-2026-09-10452" \
-d '{
"to": "5518999999999",
"type": "document",
"mediaUrl": "https://exemplo.com.br/faturas/2026-09.pdf",
"fileName": "fatura-2026-09.pdf",
"caption": "Sua fatura de setembro",
"transactional": true
}'
- A resposta é
202comstatus: "queued"; acompanhe comGET /messages/{id}(sent,delivered,readoufailed). Idempotency-Key(até 100 caracteres): repetir a requisição com a mesma chave devolve a mesma mensagem, sem reenviar. Use o número da fatura ou do pedido.- Mídias por
mediaUrl(só https) oumediaBase64, até 25 MB. transactional: trueentrega mesmo a contatos descadastrados de campanhas. Use só para fatura, aviso técnico e afins.
Grupos de endpoints¶
| Grupo | Endpoints |
|---|---|
| Conta | GET /me |
| Mensagens | POST /messages, GET /messages/{id}, GET /messages/{id}/media |
| Contatos | GET /contacts, GET /contacts/{id}, POST /contacts, PATCH /contacts/{id} |
| Conversas | GET /conversations, GET /conversations/{id}, GET /departments, POST /conversations/{id}/transfer, POST /conversations/{id}/close |
| Tickets | GET /tickets, POST /tickets |
| Webhooks | GET /webhooks, POST /webhooks, DELETE /webhooks/{id} |
Webhooks¶
| Evento | Quando |
|---|---|
message.received |
O cliente mandou uma mensagem |
message.status |
Mudou o status de uma mensagem enviada (entregue, lida, falhou) |
conversation.closed |
Uma conversa foi encerrada (discarded: true quando foi descartada) |
conversation.rated |
O cliente respondeu à pesquisa de satisfação |
ticket.created |
Um ticket foi aberto |
ping |
Teste disparado pelo botão Testar |
Cadastre pelo painel (API → Webhooks) ou pela API (POST /webhooks, permissão webhooks:manage). O destino precisa ser https. O segredo aparece uma única vez e serve para conferir a assinatura HMAC-SHA256 (sobre timestamp.corpo) de cada entrega. Os nomes dos cabeçalhos, os exemplos de verificação e o formato de cada evento estão na página /desenvolvedores do seu painel (botão Documentação na tela API).
Novas tentativas. Sem resposta 2xx, a entrega é repetida em 1 min, 5 min, 30 min, 2 h e 6 h. Depois de 10 eventos seguidos sem sucesso, o webhook é desativado: corrija o destino e clique em Ativar. Entregas mostra as últimas 30, com o botão Reenviar.
Quando algo não funciona¶
Toda resposta traz um requestId. Envie esse valor ao administrador do painel: em API → Registro de chamadas ele encontra a chamada exata, com chave, rota, resultado, tempo e IP.
| Erro | Causa comum |
|---|---|
401 unauthorized |
Chave revogada, expirada ou copiada errada |
403 insufficient_scope |
A chave não tem a permissão do endpoint |
403 ip_not_allowed |
O IP de origem não está na lista da chave |
429 rate_limited |
Acima do limite por minuto; aguarde e repita |
connection_offline |
O número de WhatsApp está desconectado no painel |
contact_opted_out |
O contato pediu para não receber campanhas; use transactional só se for mensagem transacional |