API querfalarcomigo.tech
API REST para enviar e receber mensagens de WhatsApp a partir do seu sistema. Cada cliente recebe uma instância (um número de WhatsApp) com seu próprio ID e API key.
{{BASE}}- Pela área do cliente: em
/cliente, o QR do número aparece no cartão dele (no autocadastro, assim que a ativação é paga). Também é possível receber do suporte um link de conexão (/connect/...) válido por tempo limitado. - Pelo seu sistema: consulte
GET /status; se vierqr_pending, busqueGET /qre exiba a imagem para o usuário. Repita a cada 2–3s até o status virarconnected. O QR muda a cada ~20s. - Com o status
connected, já é possível enviar mensagens e receber o webhook.
Todas as rotas exigem a API key da instância no header X-API-Key. A chave só é exibida uma vez, ao ser gerada — guarde-a no servidor, nunca no front-end/navegador. Se vazar, gere uma nova na área do cliente (botão Gerar API key) ou peça ao suporte. A antiga deixa de funcionar na hora.
curl -H "X-API-Key: zb_sua_api_key" {{BASE}}/api/instances/INSTANCE_ID/status
Erros sempre retornam JSON no formato { "error": "mensagem" }.
billing (ver Cobrança)
403Instância suspensa ou conta desativada
404QR / mensagem não disponível
409Instância não está conectada ao WhatsApp
422Idempotency-Key já usada com outro conteúdo no /send (ver Envio sem duplicar)
429Limite de proteção anti-spam — respeite o header Retry-After. O campo reason diz qual limite (ver Proteção anti-spam)
500Falha ao enviar pelo WhatsApp
O WhatsApp bane números com picos de envio, disparo em massa e conversas automáticas em loop. Para proteger o seu número, todo envio passa por uma fila com intervalo de 1,5 a 3,5 s entre mensagens (a chamada ao /send responde quando a mensagem sai) e pelos limites abaixo. Quando um limite é atingido, o /send responde 429 com reason e retryAfter (segundos).
reason | Limite |
|---|---|
per_minute / per_hour / per_day | 20 por minuto, 300 por hora e 1.500 por dia, por número conectado |
per_recipient | 6 mensagens por minuto para o mesmo destinatário (evita loop de bot). Em conversa ativa — quando o destinatário enviou uma mensagem nos últimos 2 minutos, como num menu de bot — o limite sobe para 20 por minuto (sem ultrapassar o limite geral por minuto do número) |
new_contacts | 150 conversas com contatos novos por dia (quem nunca falou com o número) |
recipient_muted | Destinatário silenciado por 15 min: ele mandou mais de 12 mensagens em 30 s. As mensagens dele também deixam de ir para o webhook nesse período |
queue_full | Mais de 60 mensagens aguardando na fila |
cooldown | Pausa de proteção (30 min): o número passou muitas vezes dos limites ou enviou o mesmo texto para mais de 40 pessoas em 1 hora (disparo em massa). Nenhum envio sai até o fim da pausa |
O estado atual aparece em GET /status, no campo protection. Recomendação: trate o 429 esperando o retryAfter e reenviando (a mensagem recusada não fica na fila; use a mesma Idempotency-Key no reenvio). Não repita sem esperar: cada recusa por limite conta, e 25 recusas em 10 minutos colocam o número numa pausa de 30 minutos (cooldown). No seu bot, prefira juntar as opções de um passo numa única mensagem.
Situação financeira da conta. Continua respondendo mesmo com a conta bloqueada, para o seu sistema mostrar o débito ao usuário. Também é possível acompanhar e pagar pela área do cliente.
curl -H "X-API-Key: zb_sua_api_key" {{BASE}}/api/instances/INSTANCE_ID/billing
{
"status": "overdue", // active | pending | overdue | blocked | inactive
"blocked": false,
"plan": { "name": "Plano Mensal", "cycle": "monthly", "amount": 59.9, "amountFormatted": "R$ 59,90", "billingDay": 10 },
"nextDueDate": "2026-10-10",
"pendingTotal": 59.9,
"pendingTotalFormatted": "R$ 59,90",
"pending": [
{ "id": "42df333b12ef", "description": "Plano Mensal — 10/2026", "amount": 59.9,
"dueDate": "2026-10-10", "overdue": true, "daysOverdue": 3 }
],
"blockOnOverdue": true,
"graceDays": 5,
"blocksOn": "2026-10-16", // a partir desta data a API passa a responder 402
"lastPayment": { "dueDate": "2026-09-10", "paidAt": "2026-09-09T14:02:11.000Z", "amount": 59.9 }
}
active | Em dia, nada em aberto. |
pending | Mensalidade disponível para pagamento, ainda não vencida. |
overdue | Há mensalidade vencida, mas a conta ainda funciona (carência ou conta sem trava). |
blocked | Bloqueada por falta de pagamento: os demais endpoints respondem 402. Libera automaticamente quando o pagamento é confirmado. |
inactive | Conta desativada. |
Datas no formato AAAA-MM-DD, no horário de Brasília.
Body opcional { "invoiceId": "..." } (um dos pending[].id do /billing); sem ele, gera o da mensalidade mais antiga. Reaproveita o mesmo PIX enquanto ele estiver válido. Funciona com a conta bloqueada. Acompanhe com GET /api/instances/:id/billing/pix/:invoiceId — quando status virar paid, a conta já está liberada.
{
"invoiceId": "42df333b12ef",
"status": "pending", // pending | paid | expired
"amountFormatted": "R$ 59,90",
"description": "Plano Mensal — 11/2026",
"dueDate": "2026-11-01",
"brCode": "00020101021226...6304ABCD", // PIX copia e cola
"qrCode": "data:image/png;base64,iVBORw0...",
"expiresAt": "2026-11-02T12:00:00.000Z"
}
curl -H "X-API-Key: zb_sua_api_key" {{BASE}}/api/instances/INSTANCE_ID/status
{
"status": "connected",
"phone": "5511999999999",
"disconnectedSince": null,
"protection": {
"state": "ok", "sentLastMinute": 2, "sentLastHour": 41, "sentLast24h": 380,
"newContactsLast24h": 12, "queued": 0,
"refusedLast24h": { "per_recipient": 3 },
"limits": { "perMinute": 20, "perHour": 300, "perDay": 1500, ... }
}
}
disconnectedSince: desde quando (ISO 8601) o número está sem conexão; null quando conectado. protection.refusedLast24h: envios recusados com 429 nas últimas 24 h, por reason. Os contadores ficam em memória e recomeçam a cada reinício do serviço.
connecting | Iniciando conexão |
qr_pending | Aguardando leitura do QR |
connected | Pronto para enviar/receber |
disconnected | Queda temporária, reconectando automaticamente |
logged_out | Desconectado pelo celular — chame POST /reset para gerar novo QR |
Disponível somente com status qr_pending. Retorna uma imagem PNG em data URL, pronta para usar no <img src>. Faça a chamada pelo seu back-end e repasse a imagem ao navegador — não exponha a API key no front.
{ "qr": "data:image/png;base64,iVBORw0KGgo..." }
Use para trocar o número conectado ou quando o status for logged_out. Em seguida, acompanhe /status e exiba o /qr.
curl -X POST -H "X-API-Key: zb_sua_api_key" {{BASE}}/api/instances/INSTANCE_ID/reset
| Campo | Tipo | Descrição | |
|---|---|---|---|
to | string | obrig. | Destino. Aceita: telefone com DDI (5511999999999; sem DDI assume Brasil), identificador 170252671410263@lid ou grupo 120363...@g.us. Para responder uma mensagem recebida, use o campo replyTo do webhook. |
message | string | texto* | Texto (até 4096 caracteres) |
mediaUrl | string | imagem* | URL https pública de uma imagem (até 10MB) |
caption | string | opcional | Legenda da imagem |
poll | object | enquete* | Enquete: { "question": "...", "options": ["...", "..."], "multiple": false }. Ver Enquete. |
sendAt | string | opcional | Agenda o envio para esta data e hora (ISO 8601 com fuso, ex.: 2026-12-01T09:00:00-03:00), entre 1 minuto e 30 dias à frente. Ver Envio agendado. |
* Informe message, mediaUrl ou poll. A enquete vai sozinha, sem message/mediaUrl.
| Header | Descrição |
|---|---|
Idempotency-Key | Identificador único do envio no seu sistema (ex.: pedido-123-aprovado). Até 128 caracteres entre letras, números e _ . : -. |
Se a sua requisição der timeout e você repetir o /send com a mesma chave e o mesmo corpo, a mensagem não é enviada de novo: você recebe o mesmo messageId e o header Idempotent-Replayed: true. Se o primeiro envio ainda estiver na fila, a repetição espera por ele. Mesma chave com corpo diferente retorna 422. Envios que falharam (400, 409, 429, 500…) não ficam registrados: pode repetir com a mesma chave.
A chave vale por 24 horas, por instância. Ela fica só na memória do servidor: um reinício ou atualização do serviço apaga as chaves, e nesse caso uma repetição envia de novo.
curl -X POST {{BASE}}/api/instances/INSTANCE_ID/send \
-H "X-API-Key: zb_sua_api_key" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: pedido-123-aprovado" \
-d '{"to": "5511999999999", "message": "Olá! Seu pedido foi aprovado."}'
$ch = curl_init('{{BASE}}/api/instances/INSTANCE_ID/send'); curl_setopt_array($ch, [ CURLOPT_POST => true, CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 30, CURLOPT_HTTPHEADER => [ 'X-API-Key: ' . getenv('WHATSAPP_API_KEY'), 'Content-Type: application/json', ], CURLOPT_POSTFIELDS => json_encode([ 'to' => '5511999999999', 'message' => 'Olá! Seu pedido foi aprovado.', ]), ]); $resp = json_decode(curl_exec($ch), true); $http = curl_getinfo($ch, CURLINFO_HTTP_CODE);
const res = await fetch('{{BASE}}/api/instances/INSTANCE_ID/send', { method: 'POST', headers: { 'X-API-Key': process.env.WHATSAPP_API_KEY, 'Content-Type': 'application/json' }, body: JSON.stringify({ to: '5511999999999', message: 'Olá!' }), }) const data = await res.json()
{ "to": "5511999999999", "mediaUrl": "https://seusite.com/boleto.png", "caption": "Seu boleto" }
{ "ok": true, "messageId": "3EB0C767D26A1D8E4A1B" }
Guarda as últimas 200 mensagens enviadas por instância, inclusive depois de reinícios do serviço. Mensagens enviadas pelo agendador trazem também scheduleId.
{
"id": "3EB0C767D26A1D8E4A1B",
"to": "5511999999999@s.whatsapp.net",
"type": "text", // text | image | poll
"status": 3,
"statusLabel": "delivered", // pending | sent | delivered | read | played | error
"timestamp": 1727359200000
}
Envie o campo poll no /send. A enquete aparece no celular e no WhatsApp Web/Desktop, e cada voto chega no seu webhook já decifrado, no evento poll.vote. A resposta é a mesma de um envio comum ({ ok, messageId }); o messageId identifica a enquete. Funciona com sendAt e Idempotency-Key, e conta nos limites anti-spam como qualquer mensagem.
question | Pergunta, até 255 caracteres. |
options | De 2 a 12 opções, sem repetir, até 100 caracteres cada. |
multiple | true permite marcar mais de uma opção (padrão false: uma só). |
lockFirstVote | true = primeiro voto vale: o primeiro voto de cada pessoa vira o resultado oficial; trocas e retiradas depois dele não mudam a contagem e chegam no poll.vote com ignored: true. Padrão false (cada troca vale). |
Limitação do WhatsApp: não existe trava de voto no app. Com lockFirstVote, a pessoa ainda consegue trocar ou retirar o voto e a enquete no celular dela mostra a escolha nova; só o resultado da API (webhook e contagem) fica travado. Se quiser avisar a pessoa, use o replyTo do evento ignorado para responder pelo /send.
curl -X POST {{BASE}}/api/instances/INSTANCE_ID/send \
-H "X-API-Key: zb_sua_api_key" \
-H "Content-Type: application/json" \
-d '{"to": "5511999999999", "poll": {"question": "Qual horário você prefere?", "options": ["09:00", "11:00", "14:00"]}}'
A contagem atual fica no GET /messages/:messageId da enquete, no campo poll: { question, options, multiple, votes: { "09:00": 2, "11:00": 0, ... }, voters }. Os votos são registrados por 30 dias após o envio; depois disso a enquete deixa de ser acompanhada.
Envie o /send com sendAt para agendar. A resposta vem na hora, com status 202:
{ "ok": true, "scheduled": true, "scheduleId": "sch_...", "sendAt": "2026-12-01T12:00:00.000Z" }
No horário, a mensagem passa pela mesma fila e pelos mesmos limites anti-spam de um envio comum, um por vez por número. Se cair num limite ou o número estiver desconectado, tentamos de novo por até 1 hora depois do horário; depois disso o agendamento fica failed. Muitos agendamentos para o mesmo horário saem aos poucos, no ritmo dos limites (por exemplo, no máximo 300 por hora). Com mediaUrl, a imagem é baixada na hora do envio: a URL precisa continuar válida até lá.
O Idempotency-Key também vale para agendar. Máximo de 1000 agendamentos pendentes por número. Agendamentos concluídos ficam disponíveis por 7 dias.
GET /schedules | Lista os agendamentos do número: pendentes primeiro (do mais próximo), depois os concluídos (até 100). |
GET /schedules/:scheduleId | Um agendamento. 404 se não existir. |
DELETE /schedules/:scheduleId | Cancela um agendamento pendente. 409 se ele já foi enviado, está sendo enviado ou já foi cancelado. |
{
"id": "sch_...", "to": "5511999999999", "type": "text",
"message": "Lembrete: sua consulta é amanhã às 9h", "mediaUrl": null, "caption": null,
"sendAt": "2026-12-01T12:00:00.000Z",
"status": "scheduled", // scheduled | sending | sent | failed | canceled
"attempts": 0, "messageId": null, "error": null,
"createdAt": "...", "finishedAt": null
}
Quando sai, o agendamento ganha messageId e as mudanças de status chegam no evento message.status, com scheduleId. Se falhar de vez, também chega um message.status com status: 0, statusLabel: "error", id: null, scheduleId e error. Se o serviço reiniciar exatamente durante um envio, o agendamento fica failed: ele pode não ter saído, mas nunca é enviado em dobro.
Aceita o identificador com ou sem o sufixo (170252671410263 ou 170252671410263@lid). Retorna 404 se o WhatsApp ainda não informou o telefone desse contato — nesse caso, responda usando o próprio @lid.
{ "lid": "170252671410263@lid", "jid": "5511999999999@s.whatsapp.net", "phone": "5511999999999" }
| Campo | Tipo | Descrição |
|---|---|---|
webhookUrl | string | null | URL https pública. null desativa o webhook. |
ignoreGroups | boolean | true para não receber mensagens de grupos (padrão false). |
events | string[] | Eventos que você quer receber: message.received, message.status, instance.status, poll.vote. Padrão: ["message.received", "poll.vote"]. O webhook.test é sempre enviado quando você pede um teste. |
Use GET /api/instances/:id/webhook para consultar a configuração atual.
curl -X PUT {{BASE}}/api/instances/INSTANCE_ID/webhook \
-H "X-API-Key: zb_sua_api_key" \
-H "Content-Type: application/json" \
-d '{"webhookUrl": "https://seusistema.com/whatsapp/webhook", "ignoreGroups": true}'
{
"instanceId": "a1b2c3d4e5f6",
"event": "message.received",
"eventId": "evt_6f1c2a9b0d3e4f5a6b7c8d9e",
"data": {
"id": "3EB0...",
"from": "170252671410263@lid",
"isGroup": false,
"phone": "5511999999999",
"senderJid": "5511999999999@s.whatsapp.net",
"senderLid": "170252671410263@lid",
"participant": null,
"replyTo": "5511999999999",
"pushName": "João",
"timestamp": 1727359200,
"type": "conversation",
"text": "Oi, quero saber do meu pedido"
}
}
eventId | Identificador desta entrega; igual ao header X-Webhook-Id e o mesmo em todas as tentativas (ver Reenvio). |
from | Conversa de origem, no formato bruto do WhatsApp. Pode ser ...@s.whatsapp.net, ...@lid (contato) ou ...@g.us (grupo). |
isGroup | true se veio de um grupo. |
phone | Telefone de quem enviou (só dígitos, com DDI). Use para identificar o contato no seu sistema. null se o WhatsApp não informou. |
senderJid | JID de quem enviou — em telefone quando conhecido, senão o @lid. |
senderLid | Identificador @lid de quem enviou, quando houver. |
participant | Em grupos: JID bruto de quem enviou. |
replyTo | Valor pronto para o campo to do /send: telefone, ou o @lid quando o telefone não é conhecido, ou o grupo. |
Sobre o @lid: o WhatsApp está migrando contatos para um identificador anônimo (LID), então from pode vir como ...@lid mesmo em conversas privadas — trate como regra, não exceção. Sempre que o WhatsApp informa o telefone, ele vem em phone. Se phone vier null, responda com replyTo (o @lid funciona no /send) e tente GET /lid/:lid depois.
Cada chamada traz X-Webhook-Timestamp e X-Webhook-Signature: sha256=<hex>, um HMAC-SHA256 de timestamp + "." + corpo_bruto com o segredo do webhook (whsec_..., visível na área do cliente, no botão Webhook de cada número). Rejeite chamadas com assinatura inválida ou timestamp com mais de 5 minutos. A assinatura é refeita a cada tentativa de reenvio, com timestamp novo.
Também vêm os headers X-Webhook-Id (igual a eventId) e X-Webhook-Attempt (1 na primeira tentativa).
$secret = getenv('WHATSAPP_WEBHOOK_SECRET'); $body = file_get_contents('php://input'); $ts = $_SERVER['HTTP_X_WEBHOOK_TIMESTAMP'] ?? ''; $sig = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? ''; $expected = 'sha256=' . hash_hmac('sha256', $ts . '.' . $body, $secret); if (!hash_equals($expected, $sig) || abs(time() - (int) $ts) > 300) { http_response_code(401); exit; } $event = json_decode($body, true); // ... processa $event['data']['text'] http_response_code(200);
import { createHmac, timingSafeEqual } from 'crypto' function verify(rawBody, ts, sig, secret) { const expected = 'sha256=' + createHmac('sha256', secret).update(`${ts}.${rawBody}`).digest('hex') return sig?.length === expected.length && timingSafeEqual(Buffer.from(sig), Buffer.from(expected)) && Math.abs(Date.now() / 1000 - Number(ts)) < 300 }
Só chegam se você incluir o evento em events no PUT /webhook (ou marcar no painel). Usam a mesma assinatura, eventId e reenvio dos demais eventos.
{
"instanceId": "a1b2c3d4e5f6",
"event": "message.status",
"eventId": "evt_...",
"data": {
"id": "3EB0C767D26A1D8E4A1B", // messageId devolvido pelo /send
"to": "5511999999999@s.whatsapp.net",
"status": 4,
"statusLabel": "read", // sent | delivered | read | played | error
"timestamp": 1727359260000
}
}
O status só avança (um recibo atrasado de "entregue" não chega depois de "lida"). Vale para as últimas 200 mensagens enviadas pela API (o histórico é mantido entre reinícios); mensagens mandadas direto pelo celular não geram este evento. Envios do agendador trazem também scheduleId. Em grupos, "entregue"/"lida" refletem o recibo geral do WhatsApp, não o de cada participante.
{
"instanceId": "a1b2c3d4e5f6",
"event": "instance.status",
"eventId": "evt_...",
"data": { "status": "disconnected", "since": "2026-11-13T14:00:00.000Z" }
}
disconnected | Sem conexão há 2 minutos (quedas rápidas não geram evento). since = início da queda. |
logged_out | Sessão encerrada no celular: enviado na hora. Gere um QR novo com POST /reset. |
connected | Voltou a funcionar. Só é enviado depois de um disconnected ou logged_out. since = momento da volta. |
O estado da queda fica em memória: se o serviço reiniciar com o número parado, o disconnected pode ser enviado de novo. Trate o evento como "estado atual", não como contagem de quedas.
{
"instanceId": "a1b2c3d4e5f6",
"event": "poll.vote",
"eventId": "evt_...",
"data": {
"pollMessageId": "3EB0C767D26A1D8E4A1B", // messageId devolvido pelo /send
"question": "Qual horário você prefere?",
"selectedOptions": ["14:00"],
"locked": false, // enquete com lockFirstVote
"ignored": false, // true = troca/retirada depois do primeiro voto (não muda o resultado)
"lockedSelection": null, // com a trava: o voto que vale
"voter": "5511999999999@s.whatsapp.net",
"phone": "5511999999999",
"senderLid": "170252671410263@lid",
"isGroup": false,
"replyTo": "5511999999999",
"pushName": "João",
"timestamp": 1727359200
}
}
selectedOptions traz a seleção completa e atual da pessoa, não um incremento: se ela trocar de opção, chega um novo poll.vote com a escolha nova; lista vazia ([]) significa que ela retirou o voto. Guarde o último voto por pollMessageId + voter (com lockFirstVote, use lockedSelection e ignore os eventos com ignored: true). Só vale para enquetes enviadas pela API; votos em enquetes criadas direto no celular continuam chegando como message.received (tipo pollUpdateMessage, sem o conteúdo do voto). Os votos são contados mesmo sem webhook configurado.
Responda com qualquer status 2xx em até 10 segundos para confirmar o recebimento. Se o seu servidor estiver fora do ar, demorar mais de 10 s ou responder 408, 429 ou 5xx, reenviamos o mesmo evento até 5 vezes, depois de 10 s, 30 s, 2 min, 10 min e 30 min. Outros códigos (4xx, 3xx) contam como recusa definitiva e não são reenviados; redirecionamentos não são seguidos.
Trate repetições: o mesmo evento pode chegar mais de uma vez (por exemplo, se o seu servidor processou mas a resposta se perdeu). Guarde o X-Webhook-Id (ou o data.id da mensagem) e ignore os que já processou.
Os reenvios pendentes são cancelados se o webhook for desativado ou a instância for suspensa. Se você trocar a URL, as próximas tentativas vão para a URL nova. Os reenvios pendentes ficam só na memória do servidor e se perdem num reinício ou atualização do serviço.
Envia agora para a URL configurada um evento webhook.test, assinado como os demais, numa única tentativa (sem reenvio), e devolve o resultado. Funciona mesmo com o número desconectado. Limite: 5 testes por minuto. Retorna 400 se o webhook não estiver configurado.
curl -X POST -H "X-API-Key: zb_sua_api_key" {{BASE}}/api/instances/INSTANCE_ID/webhook/test
{ "ok": false, "eventId": "evt_...", "status": "failed", "httpStatus": 404, "error": "HTTP 404" }
{ "instanceId": "a1b2c3d4e5f6", "event": "webhook.test", "eventId": "evt_...", "data": { "id": "test_...", "timestamp": 1727359200 } }
Seu sistema deve responder 2xx ao webhook.test e ignorar o conteúdo. Eventos com event desconhecido também devem ser aceitos e ignorados.
As últimas 100 entregas da instância, da mais recente para a mais antiga. Ficam só na memória do servidor: a lista zera a cada reinício ou atualização do serviço. O corpo do evento não é guardado.
{
"deliveries": [{
"eventId": "evt_6f1c2a9b0d3e4f5a6b7c8d9e",
"event": "message.received",
"messageId": "3EB0...",
"status": "retrying", // pending | retrying | delivered | failed | canceled
"attempts": 2,
"createdAt": "2026-11-09T14:00:00.000Z",
"lastAttemptAt": "2026-11-09T14:00:10.000Z",
"lastHttpStatus": 503,
"lastError": "HTTP 503",
"nextAttemptAt": "2026-11-09T14:00:40.000Z"
}]
}