Pular para conteúdo

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:

  1. Clique em Nova chave e dê um nome que identifique a integração (ex.: "ERP - envio de faturas").
  2. Marque só as permissões necessárias. Acesso total pede confirmação e deve ficar restrito a integrações internas.
  3. 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.
  4. 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

curl https://<domínio>/api/v1/me -H "Authorization: Bearer $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 é 202 com status: "queued"; acompanhe com GET /messages/{id} (sent, delivered, read ou failed).
  • 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) ou mediaBase64, até 25 MB.
  • transactional: true entrega 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