#WL API (zap-api) — referência da API (v0.4, Fases 1 a 3)

Contrato estável para clientes (ex.: Agenda Pro) e para o painel. Mudanças incompatíveis só com nova versão. Rotas, nomes de campos e payloads de webhook seguem a Z-API sempre que possível.

#Autenticação

• Client-Token global: variável CLIENT_TOKEN ou arquivo data/client-token. Vale para todas as instâncias.
• Client-Token de conta: definido em PUT /admin/accounts/{accountId}. Só dá acesso às instâncias daquela conta; para as demais, a resposta é 404 instância não encontrada.
• Admin-Token: variável ADMIN_TOKEN ou arquivo data/admin-token.
• Partner-Token: variável PARTNER_TOKEN ou arquivo data/partner-token.
• Erros: {"error": "mensagem"} com HTTP 400 (validação), 401 (token), 402 (assinatura sem validade), 403 (IP fora da allowlist), 404 (instância/item), 429 (rate limit, com Retry-After) ou 500.
• Rate limit por token (instância, conta ou parceiro): RATE_LIMIT_RPS requisições/s, com rajada de 2×.
• Corpo sempre JSON (Content-Type: application/json), até 150 MB.

Toda rota de instância também existe em /admin/instances/{id}/<rota> (sem o token da instância, com Admin-Token). Exemplo: GET /admin/instances/{id}/qr-code-image.

Nos exemplos:

I=http://localhost:8080/instances/$ID/token/$TOKEN
H='-H "Client-Token: $CT" -H "Content-Type: application/json"'

#1. Conexão

O QR muda a cada ~20 s; chame de novo para pegar o atual. Após ~2 min sem leitura o pareamento expira e a próxima chamada começa outro.

#2. Envio de mensagens

Todas as rotas send-* respondem na hora, antes do envio real:

{"zaapId": "32 hex", "messageId": "3EB0...", "id": "3EB0..."}

O resultado chega depois no webhook delivery (DeliveryCallback, com error se falhou).

Campos comuns: phone (obrigatório: DDI+DDD+número, ex. 5567999999999, ou <id>-group), delayMessage (1–15 s, opcional; substitui o delay da instância), viewOnce (imagem/áudio/vídeo).

Mídia (image, audio, video, document, sticker) aceita URL http(s), base64 puro ou data URI (data:image/png;base64,...). Limite de 100 MB.

curl -s -X POST $I/send-image -H "Client-Token: $CT" -H 'Content-Type: application/json' \
  -d '{"phone":"5567999999999","image":"https://exemplo.com/foto.jpg","caption":"Olá"}'

#3. Fila

As mensagens ficam numa fila persistente (SQLite) por instância e saem uma por vez, com delay aleatório entre delayMin e delayMax segundos (padrão 1–3 s). Sobrevive a reinícios. Se a instância cair, a fila espera a reconexão. Uma mensagem que estava sendo enviada no momento de uma queda vira FAILED, para nunca sair duplicada.

Configurações da fila:

#4. Webhooks

value vazio desliga o webhook. Entrega: POST JSON; se a resposta não for 2xx, tenta de novo em 2, 4 e 8 s.

#Payloads

ReceivedCallback (received):

{
  "type": "ReceivedCallback", "instanceId": "...", "messageId": "...",
  "phone": "5567999999999", "fromMe": false, "momment": 1794278655000, "status": "RECEIVED",
  "chatName": "Fulano", "senderName": "Fulano", "senderPhoto": null, "photo": null,
  "senderLid": "123@lid", "connectedPhone": "5567...", "isGroup": false, "participantPhone": null,
  "isNewsletter": false, "isStatusReply": false, "isEdit": false, "broadcast": false,
  "waitingMessage": false, "forwarded": false, "fromApi": false, "messageExpirationSeconds": 0,
  "text": { "message": "Oi!" }
}

Em grupos: phone = <id>-group e participantPhone = quem mandou. Uma chave por tipo:

As URLs de mídia apontam para PUBLIC_URL/media/<instância>/<arquivo aleatório> (o serviço baixa e guarda a mídia). Em produção, PUBLIC_URL precisa ser acessível pelo cliente.

DeliveryCallback (delivery): {type, instanceId, phone, zaapId, messageId, momment, error?}

MessageStatusCallback (message-status): {type, instanceId, status, ids: [...], phone, phoneDevice: 0, isGroup, momment}. status: SENT (servidor aceitou), RECEIVED (entregue), READ, PLAYED, READ_BY_ME (você leu no celular).

PresenceChatCallback (chat-presence): {type, instanceId, phone, status, lastSeen}; status: AVAILABLE, UNAVAILABLE, COMPOSING, RECORDING, PAUSED.

ConnectedCallback: {type, instanceId, connected: true, phone, momment}

DisconnectedCallback: {type, instanceId, disconnected: true, reason, error, momment}; reason: manual, logged_out, stream_replaced ou temporary_ban.

#5. Instância e perfil

#5b. Mensagens avançadas (Fase 2)

Todas entram na fila e respondem {zaapId, messageId, id}. Campos extras aceitos em qualquer send-*:

Diretas (respondem na hora):

Mensagens interativas (botões, lista, Pix, OTP, carrossel) usam o formato "native flow" do WhatsApp. Foram testadas e renderizaram num iPhone, mas o WhatsApp pode mudar isso sem aviso.

Webhooks novos (ReceivedCallback): poll: {question, pollMaxOptions, options: [{name}]}, pollVote: {pollMessageId, options: [{name}]} (votos são decifrados e traduzidos para o nome da opção), buttonsResponseMessage: {buttonId, message}, listResponseMessage: {message, title, selectedRowId}, event: {name, description, startTime, canceled, location}.

#5c. Contatos

#5d. Conversas

A lista de conversas vem do histórico recebido no pareamento e das mensagens que passam pelo serviço. Uma instância pareada antes da Fase 2 só mostra as conversas a partir de então.

#5e. Grupos

groupId/phone aceitam 120363...-group, 120363... ou 120363...@g.us.

Webhook de eventos de grupo (no webhook received): ReceivedCallback com notification e notificationParameters (telefones afetados), além de phone (grupo), participantPhone (quem fez) e participantLid. Valores de notification: GROUP_PARTICIPANT_ADD, GROUP_PARTICIPANT_INVITE, GROUP_PARTICIPANT_REMOVE, GROUP_PARTICIPANT_LEAVE, GROUP_PARTICIPANT_PROMOTE, GROUP_PARTICIPANT_DEMOTE, GROUP_CHANGE_SUBJECT, GROUP_CHANGE_DESCRIPTION, GROUP_CHANGE_ICON, GROUP_CHANGE_INVITE_LINK (+invitationCode, invitationLink), GROUP_CHANGE_ANNOUNCE, GROUP_CHANGE_RESTRICT, GROUP_SUSPENDED, GROUP_UNSUSPENDED.

#5f. Privacidade

Respostas: {success: true}. contactsBlacklist (adicionar/remover contatos da lista de exceções) ainda responde 501.

#LID

O WhatsApp está trocando telefones por LID (123456@lid). O motor converte LID → telefone sempre que conhece o vínculo, e os webhooks trazem os dois: phone + chatLid (conversa individual), senderLid e, em grupos, participantPhone + participantLid. Em qualquer rota, phone também aceita 123456@lid.

#6. API admin (painel)

Header Admin-Token.

GET /admin/instances também filtra por ?tagId=, e o objeto instância traz "tags": ["id", ...]. 2FA: o painel já faz TOTP por conta própria, então o motor não guarda campos de 2FA.

#Cobrança (assinatura por instância)

Estados (subscription.status): trial (2 dias, TRIAL_DAYS), ativa, pendente (trial vencido sem pagamento), em_cancelamento (continua ativa até periodEnd, sem estorno), cancelada, inadimplente (falha de pagamento ou período vencido há mais de BILLING_GRACE_DAYS). paymentStatus em inglês: TRIAL, ACTIVE, PENDING, CANCELLATION_IN_PROGRESS, CANCELED, OVERDUE. isento (cortesia do admin) aparece como ACTIVE, com due: null e subscription.exempt: true. subscription também traz blocked, blockedReason e blockedAt (bloqueio do admin). POST /admin/instances aceita "exempt": true para a instância já nascer isenta.

Sem assinatura válida, send-* responde 402; depois de BILLING_DISCONNECT_DAYS dias a instância é desconectada (suspended: true) mas a sessão continua salva, e reativar reconecta sem novo QR. Instâncias criadas antes da cobrança existir ficam como ativa, sem vencimento. BILLING_ENFORCE=0 desliga o bloqueio (desenvolvimento).

Eventos do Stripe tratados: checkout.session.completed → ativa; invoice.paid / invoice.payment_succeeded → ativa + periodEnd; invoice.payment_failed → inadimplente; customer.subscription.updated (com cancel_at_period_end) → em_cancelamento / ativa; customer.subscription.deleted → cancelada. A instância é localizada por metadata.instance_id (o checkout já envia), pelo id da assinatura ou pelo cliente. Uma assinatura Stripe por instância.

O objeto instância do admin também traz subscription, paymentStatus, due, proxy e remote (true quando a instância roda em outro servidor do cluster).

Objeto instância:

{
  "id": "32 hex", "token": "24 hex", "name": "Agenda Pro", "createdAt": "2026-11-10T02:12:54Z",
  "accountId": "conta-a", "tags": ["f76e2a5d719fbc1d"],
  "connected": true, "session": true, "phone": "5567...", "error": "",
  "lastPhone": "5567...", "lastDisconnectedAt": "2026-11-10T03:00:00Z", "lastDisconnectReason": "logged_out",
  "webhooks": {"received": "", "delivery": "", "messageStatus": "", "connected": "", "disconnected": "", "chatPresence": ""},
  "settings": {"notifySentByMe": false, "autoReadMessage": false, "callRejectAuto": false, "callRejectMessage": "",
               "delayMin": 1, "delayMax": 3, "disableEnqueueWhenDisconnected": false,
               "receiveFilters": {"ignoreGroups": false, "ignorePrivate": false, "ignoreText": false,
                                  "ignoreImage": false, "ignoreVideo": false, "ignoreAudio": false, "ignoreDocument": false}}
}

lastPhone é o último número que conectou (continua preenchido depois de desconectar). lastDisconnectedAt (RFC3339 ou null) e lastDisconnectReason (manual, logged_out, stream_replaced, temporary_ban) registram a última desconexão. Quedas momentâneas de rede, em que o motor reconecta sozinho, não contam.

Log de mensagem (messages[]): {zaapId, instanceId, messageId, direction: "in"|"out", type, phone, fromMe, status, error?, createdAt, sentAt?, deliveredAt?, readAt?} (tempos em ms). status de saída: QUEUED, SENDING, SENT, RECEIVED, READ, PLAYED, FAILED, CANCELED. Mensagens enviadas pelo próprio celular entram como direction: "out", fromMe: true.

Métricas:

{
  "from": "2026-10-11", "to": "2026-11-09", "instanceId": "",
  "totals": {"sent": 11, "received": 6},
  "byType": {"sent": {"text": 3, "image": 1, ...}, "received": {"text": 0, ...}},
  "daily": [{"day": "2026-11-09", "sent": 11, "received": 6}],
  "rows": [{"instanceId", "day", "direction": "sent|received", "type", "count"}]
}

type ∈ text, image, audio, video, document, link, contact, location, sticker. daily traz todos os dias do período (zeros incluídos) para o gráfico. Dia no fuso do servidor.

Compatibilidade: POST /instances com Client-Token também cria instância (mesmo corpo e resposta). Com o Client-Token de uma conta, a instância fica nessa conta.

#7. Partner API (revenda)

Header Authorization: Bearer <Partner-Token>; não usa Client-Token. A Z-API não publica os caminhos de todas estas rotas; os abaixo seguem o padrão integrator/on-demand dela.

Exclusão só para instâncias desconectadas e com assinatura trial, pendente (sem assinatura Stripe aberta) ou cancelada. Tipos de recusa: INSTANCE_STILL_CONNECTED, INSTANCE_NOT_ELIGIBLE, INSTANCE_HAS_ACTIVE_SUBSCRIPTION, INSTANCE_PAYMENT_STATUS_MISSING, INSTANCE_NOT_FOUND, INTERNAL_ERROR.

Proxy: HTTP, HTTPS ou SOCKS5 por instância. Se o proxy não responder em 3 tentativas, a instância conecta sem proxy e o webhook de proxy recebe {type: "ProxyCallback", instanceId, error}. me mostra proxyUrl e useProxy.

#8. Vários servidores (cluster)

Com Postgres, vários servidores podem rodar juntos. Cada instância roda em um só servidor (advisory lock no Postgres); quem recebe uma chamada de instância de outro servidor repassa ao dono (SERVER_URL). Se um servidor cai, outro assume as instâncias dele em até ~15 s, e as sessões continuam sem novo QR. Listas (/admin/instances, GET /instances) podem levar até 15 s para refletir mudanças feitas em outro servidor.