6. Instâncias WhatsApp#
Uma instância representa uma sessão WhatsApp conectada.
POST/v1/instances#
Cria uma nova instância.
Auth: Owner, Admin
Request:
{
"name": "Atendimento Principal",
"provider": "wwebjs"
}
provider é opcional. Quando omitido, usa o backend default da frota; envie
"whatsmeow", "wwebjs" ou "meta_cloud" somente quando precisar forçar um
backend específico (meta_cloud exige META_CLOUD_ENABLED=true no ambiente).
channel é a forma user-facing de escolher o tipo de conexão — quando
presente, vence o provider:
channel |
Significado |
|---|---|
"whatsapp" |
WhatsApp não-oficial (QR Code; backend default da frota — o engine interno não é exposto) |
"whatsapp_official" |
WhatsApp Cloud API oficial da Meta (meta_cloud — sem QR; credenciamento por WABA/token) |
Resposta 201:
{
"id": "84c2e480-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"name": "Atendimento Principal",
"status": "DISCONNECTED",
"supports_device_info": false,
"channel": "whatsapp",
"capabilities": {
"supports_qr": true,
"supports_pairing_code": false,
"supports_templates": false,
"requires_service_window": false,
"supports_groups": true,
"supports_status_feed": true,
"supports_calls": true,
"supports_presence": false,
"requires_proxy": true,
"supports_device_info": false
},
"phone": "",
"created_at": "2026-03-07T10:00:00Z",
"updated_at": "2026-03-07T10:00:00Z"
}
Canal e matriz de capacidades (channel + capabilities)#
Toda instância retorna channel ("whatsapp" | "whatsapp_official") e a
matriz capabilities. Clientes DEVEM ramificar por capability (nunca por nome
de backend — o engine interno não faz parte do contrato):
| Capability | whatsapp (não-oficial) |
whatsapp_official (Cloud API) |
|---|---|---|
supports_qr |
true |
false (credenciamento por WABA/token) |
supports_pairing_code |
depende do backend | false |
supports_templates |
false |
true (templates HSM aprovados) |
requires_service_window |
false |
true (janela de atendimento de 24h) |
supports_groups |
true |
false |
supports_status_feed |
true |
false |
supports_calls |
true |
false |
supports_presence |
depende do backend | false |
requires_proxy |
true (túnel dedicado por instância) |
false (Graph API é o egress sancionado) |
supports_device_info |
depende do backend | false |
"Depende do backend": dentro do canal não-oficial, o engine interno (invisível ao cliente) determina algumas capacidades — consulte sempre o valor retornado na própria instância em vez de assumir.
GET/v1/instances#
Lista todas as instâncias da empresa.
Auth: Owner, Admin
Resposta 200:
[
{
"id": "84c2e480-...",
"name": "Atendimento Principal",
"status": "CONNECTED",
"supports_device_info": true,
"phone": "554137984905",
"connected_at": "2026-03-07T10:05:00Z",
"last_seen": "2026-03-07T12:00:00Z",
"last_activity_at": "2026-03-07T12:00:00Z",
"desired_state": "CONNECTED",
"tier": "healthy",
"profile_name": "Empresa LTDA",
"profile_pic_url": "https://...",
"ban_expiry": null,
"ban_reason": "",
"proxy": {
"ip_address": "200.x.x.x",
"city": "br-saopaulo",
"isp": "Vivo",
"assigned_at": "2026-03-07T10:00:00Z"
},
"created_at": "2026-03-07T10:00:00Z",
"updated_at": "2026-03-07T12:00:00Z"
}
]
Campos omitidos quando vazios:
last_erroraparece so quando a instância teve problema (limpo ao conectar);ban_expiry/ban_reasonso após ban temporario;disconnected_at/offline_duration_seconds/offline_duration_human/offline_alert_levelso quando offline;last_logged_out_401_atso após restrição 401;proxyso quando ha IP dedicado vinculado.supports_device_infoindica seGET /v1/instances/{instanceId}/devicee suportado para a instância.falseem instânciaswwebjs; clientes devem checar esta capability antes de chamar o endpoint.tiere calculado em tempo de resposta:healthy,stale,degraded,offline,critical_offline,intentional,pending,banned.GET /v1/instancesNÃO retornauptime— esse campo aparece apenas emGET /v1/instances/{instanceId}.
GET/v1/instances/{instanceId}#
Retorna detalhes de uma instância.
Auth: Owner, Admin
Resposta 200:
{
"id": "84c2e480-...",
"name": "Atendimento Principal",
"status": "CONNECTED",
"supports_device_info": true,
"phone": "554137984905",
"connected_at": "2026-03-07T10:05:00Z",
"last_seen": "2026-03-07T12:00:00Z",
"last_activity_at": "2026-03-07T12:00:00Z",
"disconnected_at": null,
"tier": "healthy",
"offline_duration_seconds": 0,
"offline_duration_human": "",
"offline_alert_level": "",
"ban_expiry": null,
"ban_reason": "",
"last_logged_out_401_at": null,
"desired_state": "CONNECTED",
"profile_name": "Empresa LTDA",
"proxy": {
"ip_address": "200.x.x.x",
"city": "br-saopaulo",
"isp": "Vivo",
"assigned_at": "2026-03-07T10:00:00Z"
},
"proxy_health_ok": true,
"proxy_health_checked_at": "2026-03-07T11:58:30Z",
"recover_proxy_eligible": false,
"created_at": "2026-03-07T10:00:00Z",
"updated_at": "2026-03-07T12:00:00Z",
"uptime": "1h 55m 0s"
}
profile_pic_urlaparece apenas quando ha avatar em cache.uptimeaparece apenas quandostatus=CONNECTED. Diferente da listagem, este objeto NÃO retornalast_error.
O que proxy_health_ok significa (e o que NÃO significa)#
| Campo | O que é |
|---|---|
proxy_health_ok |
Veredito da última sonda do TÚNEL do IP dedicado da instância: um round-trip assinado que sai pelo proxy e volta na nossa própria API ("pong"), rodado a cada ~5min. Ausente quando não há proxy vinculado. |
proxy_health_checked_at |
Quando aquele veredito foi produzido. Ausente = o proxy nunca foi sondado (diferente de sondado-e-falhou). |
Não é um teste de alcance ao WhatsApp, e false não implica sessão caída — um socket já aberto continua carregando tráfego enquanto a sonda falha. Leia como "o túnel respondeu / não respondeu", e sempre junto com o timestamp: um false de 90s atrás (o túnel está fora AGORA) e um false de 3h atrás (foi a última coisa que ouvimos antes de a sondagem parar) pedem reações opostas. Para saber se a sessão está de pé, use status/connection.update; para saber se o túnel está de pé, use este par.
Erros:
404- Instância não encontrada
PATCH/v1/instances/{instanceId}#
Renomeia a instância (label interno Catcher). O nome não afeta o perfil WhatsApp; ele e usado apenas no Console e nas integrações que listam instâncias.
Auth: Owner, Admin
Request:
{
"name": "Atendimento SP"
}
| Campo | Tipo | Obrigatório | Descricao |
|---|---|---|---|
name |
string | sim | 3-80 caracteres após trim. Único por empresa. |
Resposta 200: Objeto de instância com o novo name.
Erros:
400 BAD_REQUEST-namefora do tamanho permitido (3-80)404 INSTANCE_NOT_FOUND- instância não pertence a empresa autenticada409 DUPLICATE_INSTANCE_NAME- já existe outra instância com esse nome na mesma empresa
Notas:
- Renomear sempre o mesmo valor (sem alteração real) e idempotente: retorna
200com a instância atual sem tocar o DB. - A operação não toca whatsmeow nem reinicia a sessão — e uma alteração puramente de label no DB do tenant.
GET/v1/instances/{instanceId}/settings#
Retorna configurações operacionais da instância.
Auth: Owner, Admin
Resposta 200:
{
"instance_id": "84c2e480-7c70-4c43-9bb3-f8e5f9ef2e53",
"humanize_enabled": true,
"media_jitter_enabled": true,
"anti_spam_guard_enabled": true,
"contact_limit_mode": "off",
"anti_spam_temperature_enabled": false,
"temperature_curve": { "cold": 3, "warm": 5, "engaged": 7, "hot": 10, "very_hot": 15 },
"max_outbound_without_inbound": 2,
"passive_mode_enabled": false,
"auto_read_messages": false,
"status_media_download": false,
"auto_reject_calls": false,
"auto_reject_message": "No momento nao consigo atender chamadas.",
"business_hours_enabled": false,
"business_hours_start": 8,
"business_hours_end": 18,
"business_hours_tz": "America/Sao_Paulo",
"business_hours_weekdays_only": true,
"link_spam_enabled": true,
"link_spam_threshold": 3
}
| Campo | Tipo | Descricao |
|---|---|---|
instance_id |
string | ID da instância |
humanize_enabled |
bool | Controla a humanizacao automática de mensagens de texto enviadas pela API. Default true. |
media_jitter_enabled |
bool | Controla jitter de bytes por envio de mídia outbound antes do upload para a Meta. Default true. |
anti_spam_guard_enabled |
bool | Ativa o guard anti-spam (conteúdo duplicado em 24h + limite consecutivo sem resposta). Default true. |
contact_limit_mode |
string | O limite opcional de envios seguidos a um contato sem resposta: off (default, sem limite por contato), temperature (curva por engajamento, temperature_curve) ou fixed (o mesmo número para todo contato, max_outbound_without_inbound). Um modo por instância. |
anti_spam_temperature_enabled |
bool | Derivado: true quando contact_limit_mode=temperature. Mantido para clientes antigos. |
temperature_curve |
object | Cap de envios consecutivos sem resposta por tier de engajamento. Campos: cold, warm, engaged, hot, very_hot (inteiros). Sempre presente — quando a instância não tem override, devolve o default 3/5/7/10/15. As faixas de score (0-19 / 20-39 / 40-59 / 60-79 / 80-100) são fixas; só os caps são configuráveis. Só vale com contact_limit_mode=temperature. |
max_outbound_without_inbound |
int | Limite fixo de envios consecutivos sem resposta (1-10, default 2). Só vale com contact_limit_mode=fixed. |
passive_mode_enabled |
bool | Quando true, bloqueia envios iniciados pela API para a instância. |
auto_read_messages |
bool | Marca automaticamente mensagens recebidas como lidas. |
status_media_download |
bool | Baixa automaticamente a foto/vídeo/áudio de todo status de contato. Default false: o status.received chega com has_media: true e sem media_id, e um status é baixado sob demanda via POST /v1/instances/{id}/status/{statusId}/media. Provider wwebjs. |
auto_reject_calls |
bool | Rejeita automaticamente chamadas recebidas. |
auto_reject_message |
string | Mensagem opcional enviada/registrada para chamadas rejeitadas automaticamente. |
business_hours_enabled |
bool | Ativa bloqueio por horário comercial. |
business_hours_start |
int | Hora inicial permitida, 0-23. |
business_hours_end |
int | Hora final permitida, 1-24. |
business_hours_tz |
string | Timezone IANA usada na regra de horário comercial. |
business_hours_weekdays_only |
bool | Quando true, aplica horário comercial apenas em dias úteis. |
link_spam_enabled |
bool | Ativa a regra de anti-spam por links. |
link_spam_threshold |
int | Limite da regra de links, 1-10000. |
Erros:
404 INSTANCE_NOT_FOUND- instância não pertence a empresa autenticada
PATCH/v1/instances/{instanceId}/settings#
Atualiza configurações operacionais da instância. Aceita PATCH parcial — qualquer combinação dos campos abaixo.
Auth: Owner, Admin
Request:
{
"humanize_enabled": false,
"media_jitter_enabled": true,
"anti_spam_guard_enabled": true,
"contact_limit_mode": "temperature",
"temperature_curve": { "cold": 4, "warm": 6, "engaged": 8, "hot": 12, "very_hot": 20 },
"max_outbound_without_inbound": 3,
"passive_mode_enabled": false,
"auto_read_messages": true,
"auto_reject_calls": true,
"auto_reject_message": "Nao atendemos chamadas por este canal.",
"business_hours_enabled": true,
"business_hours_start": 8,
"business_hours_end": 18,
"business_hours_tz": "America/Sao_Paulo",
"business_hours_weekdays_only": true,
"link_spam_enabled": true,
"link_spam_threshold": 3
}
| Campo | Tipo | Obrigatório | Descricao |
|---|---|---|---|
humanize_enabled |
bool | não | Ativa/desativa composing + delay aleatorio antes de SendText |
media_jitter_enabled |
bool | não | Ativa/desativa jitter de bytes por envio de mídia outbound. Quando false, o worker envia os bytes canônicos lidos do R2. |
anti_spam_guard_enabled |
bool | não | Ativa/desativa o guard anti-spam (regras abaixo). Quando false, todas as regras são puladas. |
contact_limit_mode |
string | não | off | temperature | fixed (outro valor → 400). Liga ou desliga o limite opcional por contato; o hash-dedup de 24h continua ativo em qualquer modo. |
anti_spam_temperature_enabled |
bool | não | Forma antiga: true escolhe temperature; false sai de temperature para off (um limite fixed escolhido não é tocado). |
temperature_curve |
object | não | Cap por tier {cold, warm, engaged, hot, very_hot} (inteiros). Cada valor 1-50; a curva deve ser não-decrescente (cold ≤ warm ≤ engaged ≤ hot ≤ very_hot). Envie os 5 campos. Para voltar ao padrão, mande {cold:3,warm:5,engaged:7,hot:10,very_hot:15}. |
max_outbound_without_inbound |
int | não | 1-10. Número do limite fixo; vale com contact_limit_mode=fixed. |
passive_mode_enabled |
bool | não | Ativa/desativa modo passivo. |
auto_read_messages |
bool | não | Ativa/desativa leitura automática de mensagens recebidas. |
status_media_download |
bool | não | Ativa/desativa o download automático da mídia de status de contatos (default false). |
auto_reject_calls |
bool | não | Ativa/desativa rejeição automática de chamadas. |
auto_reject_message |
string | não | Mensagem opcional, 0-500 caracteres. |
business_hours_enabled |
bool | não | Ativa/desativa regra de horário comercial. |
business_hours_start |
int | não | Hora inicial 0-23. |
business_hours_end |
int | não | Hora final 1-24. |
business_hours_tz |
string | não | Timezone IANA. |
business_hours_weekdays_only |
bool | não | Restringe horário comercial aos dias úteis. |
link_spam_enabled |
bool | não | Ativa/desativa regra de links. |
link_spam_threshold |
int | não | Limite 1-10000. |
Ao menos um dos campos e obrigatório. Os campos omitidos preservam o valor atual.
Resposta 200: Mesmo payload do GET /v1/instances/{instanceId}/settings após a atualização.
Erros:
400 MISSING_FIELD- corpo sem nenhum campo aceito400 BAD_REQUEST-max_outbound_without_inboundfora do range 1-10,business_hours_startfora de 0-23,business_hours_endfora de 1-24,link_spam_thresholdfora de 1-10000,auto_reject_messagecom mais de 500 caracteres, outemperature_curvecom valor fora de 1-50 / não-decrescente404 INSTANCE_NOT_FOUND- instância não pertence a empresa autenticada
GET/v1/instances/{instanceId}/account-pressure#
Pressão da conta: camada anti-spam por conta, que complementa as regras por contato (Anti-spam guard abaixo). Cada envio aceito é classificado:
- conversa: o contato escreveu nas últimas 72h. Nunca é contada.
- iniciado por nós: todo o resto para uma pessoa. Conta nas janelas de 10 min, 1h e 24h (contatos distintos). Contato frio, que nunca escreveu ou está calado há mais de 30 dias, pesa em dobro.
- isento: grupo, status ou newsletter.
O texto ou a legenda vira uma "impressão digital" de modelo, que ignora o nome do contato. Assim, "Oi, Maria! ..." e "Oi, Ana! ..." contam como a mesma campanha.
Modos (
ACCOUNT_PRESSURE_MODE):observe(default) só registra o veredito;enforceaplica a trava nas instâncias comaccount_pressure_enforced=true(PATCH .../settings); as demais continuam em observação.offdesliga. Os limites foram calibrados com 30 dias de tráfego real de produção.
Com a trava aplicada, um envio iniciado por nós (respostas em conversa aberta nunca são afetadas):
| Situação | Resposta |
|---|---|
| Cabe na cota | 202 normal |
| Cota de 10 min ou 1h cheia, ou já há envios segurados na instância (fila FIFO) | 202 com "held": true e "scheduled_for" (estimativa RFC3339). O envio sai sozinho quando a janela abre e então gera o message.sent de sempre. Evento send.paced. Retry com o mesmo Idempotency-Key devolve o mesmo message_id e scheduled_for |
| Teto de 24h cheio | 409 ACCOUNT_SEND_BUDGET_EXCEEDED + Retry-After: 3600 |
Padrão de acidente (template_burst, send_rate, recipient_repeat) |
423 INSTANCE_SEND_LOCKED. A instância fica travada para envios iniciados (evento instance.send_locked); os segurados ficam congelados. Só POST .../send-unlock destrava |
| Instância travada | 423 INSTANCE_SEND_LOCKED com reason e locked_at |
Uma trava (automática ou manual) vale em todos os modos exceto off, mesmo em instância sem account_pressure_enforced — o freio manual sempre freia. X-Force-Send não contorna a trava por conta (ele vale só para as regras por contato). Com o Redis fora, a trava falha aberta (o envio passa); uma instância já travada continua travada, porque a trava é coluna do banco.
{ "status": "queued", "held": true, "scheduled_for": "2026-10-21T14:23:00Z",
"message_id": "7f0c2d4e-5b1a-4c3e-9d2f-1a2b3c4d5e6f", "task_id": "held:7f0c2d4e-…", "idempotency_key": "camp-123-456" }
Auth: JWT ou API key da empresa dona da instância.
Resposta 200:
{
"instance_id": "195ce106-036b-4a65-8d51-de000bf21bdf",
"mode": "observe",
"counts": {
"initiated_10m": 9, "initiated_1h": 9, "initiated_24h": 9,
"cold_10m": 9, "cold_1h": 9, "cold_24h": 9,
"sends_last_minute": 0, "recipient_sends_10m": 0,
"template_max_10m": 9, "template_max_1h": 9
},
"assessment": { "hold": true, "lock": false, "reasons": ["quota_10m"] },
"thresholds": {
"initiated_per_10m": 16, "initiated_per_hour": 40, "initiated_per_day": 150,
"template_recipients_per_10m": 25, "sends_per_minute": 20, "same_recipient_per_10m": 15
},
"enforced": false,
"lock": null,
"held_count": 0,
"observed_at": "2026-10-20T14:13:08Z"
}
enforced é verdadeiro só com ACCOUNT_PRESSURE_MODE=enforce e account_pressure_enforced=true. lock é null ou { "locked_at", "reason", "locked_by" } (locked_by: account_pressure quando a trava foi automática, user:<id> quando manual). held_count é a fila de envios segurados.
| Campo | Descrição |
|---|---|
counts.initiated_* |
Contatos distintos que receberam mensagem iniciada por nós na janela |
counts.cold_* |
Desses, quantos estavam frios. Somam em dobro nas cotas |
counts.template_max_* |
Maior número de contatos distintos que receberam o mesmo modelo de mensagem |
counts.sends_last_minute |
Envios iniciados por nós no último minuto (padrão de loop) |
assessment.hold |
A cota de 10 min, 1h ou 24h estourou: o envio seria segurado até a janela abrir |
assessment.lock |
Padrão de acidente (mesmo modelo para 25+ contatos em 10 min, 20+ envios/min, 15+ para o mesmo contato em 10 min): a conta seria travada até um humano destravar |
assessment.reasons |
quota_10m, quota_1h, quota_24h, template_burst, send_rate, recipient_repeat |
Erros:
404 INSTANCE_NOT_FOUND- instância não pertence à empresa autenticada503 SERVICE_UNAVAILABLE- Redis indisponível para ler os contadores
POST/v1/instances/{instanceId}/send-lock#
Trava manual dos envios iniciados por nós (freio de emergência). Respostas em conversa aberta continuam passando. Auth: owner ou admin. Auditado (account_pressure.send_lock).
{ "reason": "campanha errada" }
reason é opcional (default manual, máx. 200 caracteres). Trava já existente mantém o primeiro motivo. Responde 200 com o mesmo corpo de GET .../account-pressure. Emite instance.send_locked.
POST/v1/instances/{instanceId}/send-unlock#
Única forma de sair de uma trava — nenhum processo automático destrava. Auth: owner ou admin. Auditado (account_pressure.send_unlock).
{ "discard_held": false }
Zera os sinais da rajada perdoada (o próximo envio não volta a travar pelo mesmo motivo) e mantém a cota já usada. Com discard_held: false os envios segurados voltam a sair pela fila; com true eles são descartados: o pedido fica failed e sai message.delivery_failed com reason="account_pressure_discarded" e wire_state="not_sent". Responde 200 com o corpo de GET .../account-pressure. Emite instance.send_unlocked.
Erros (lock/unlock): 400 INVALID_JSON / BAD_REQUEST (reason longo), 403 (role agent), 404 INSTANCE_NOT_FOUND.
Anti-spam guard#
Quando anti_spam_guard_enabled=true (default), todo envio outbound passa por duas regras antes de ser enfileirado:
-
Conteúdo duplicado — bloqueia apenas quando o envio repete o último conteúdo enviado pro contato (duplicata imediata, sem nada diferente no meio). Escopo
(instance_id, remote_jid), com TTL máximo de 24h:- Texto: hash do
text(trim). - Mídia: hash de
media_url|media_id + caption + file_name. - Localização: hash de
(lat, lng, name, address). - Contato: hash de
(contact_name, contact_phone). - Poll: hash de
question + options. - Template: hash de
body + footer. - Reaction/Forward/Delete/Edit ficam fora dessa regra (operam em mensagem existente).
- Reset por mensagem diferente (outbound): enviar qualquer conteúdo diferente pro mesmo contato limpa o hash anterior. Se você mandou A, depois B, pode repetir A — só a repetição imediata de A (nada diferente no meio) é bloqueada. Ajuste 2026-07-01 (mais suave, menos burocrático): antes qualquer repetição do mesmo conteúdo em 24h era bloqueada mesmo com outras mensagens no meio.
- Reset por inbound: quando o contato responde (qualquer
*events.MessagecomIsFromMe=false), TODOS os hashes pra esse(instance_id, remote_jid)são descartados. Permite que respostas curtas naturais ("sim","ok","obrigado") se repitam ao longo do dia sem disparar bloqueio. - O padrão anti-blast original (o mesmo template N vezes em sequência, nada diferente entre os envios, sem nenhuma resposta) continua sendo bloqueado — é exatamente a duplicata imediata. A reciprocidade/temperatura (regra 2) é o backstop pro blast que varia o texto.
- Texto: hash do
-
Limite de envios seguidos sem resposta — opcional, desligado por padrão (decisão de 16/11/2026: o cliente liga se quiser mais controle). Escolhido por instância em
contact_limit_mode:off(default, inclusive nas instâncias que já existiam) → nenhum limite por contato.temperature→ o limite efetivo passa a ser derivado do score por(instance_id, remote_jid)e do cap por tier emtemperature_curve(defaultcold3 ·warm5 ·engaged7 ·hot10 ·very_hot15, personalizável por instância emPATCH /settings). Bloqueio retorna409 CONFLICTcomerror_code: "BLOCKED_TEMPERATURE_LIMIT"(payload incluiremote_jid,score,tier,max_consecutive,outbound_consecutive).fixed→ vale o limite fixomax_outbound_without_inbound(1-10, default 2), rolling window 7d. Bloqueio retorna409 CONFLICTcomerror_code: "BLOCKED_NO_RECIPROCITY"(payload incluiremote_jid,count,threshold).
Nos dois modos o contador é zerado a cada mensagem recebida do contato (qualquer tipo:
text.received,sticker.received…) e conta só o envio que de fato saiu, por contato (o número com ou sem 9, com ou sem@s.whatsapp.net, é o mesmo contato).
Resumo da precedência:
anti_spam_guard_enabled |
contact_limit_mode |
Conteúdo duplicado | Limite seguido sem resposta |
|---|---|---|---|
false |
qualquer | desativado | desativado |
true |
off (default) |
ativo (hash 24h) | desativado |
true |
fixed |
ativo (hash 24h) | limite fixo max_outbound_without_inbound |
true |
temperature |
ativo (hash 24h) | curva por score (temperatura) |
Bypass: envie o header X-Force-Send: true na requisição. O guard registra audit log com audit_action=anti_spam.force_send por regra ignorada. Tenant admin/owner deve usar com critério.
POST/v1/instances/{instanceId}/connect#
Conecta a instância ao WhatsApp. Gera QR code para parear.
Auth: Owner, Admin
Request (opcional):
{
"qr_retries": 3
}
| Campo | Tipo | Obrigatório | Descricao |
|---|---|---|---|
qr_retries |
int | não | Tentativas de QR (1-3). Padrão: 1 |
Resposta 200: Objeto de instância no estado atual do DB. A operação e assincrona: a transicao CONNECTING -> QR_PENDING -> CONNECTED acontece depois no worker. O QR NÃO vem nesta resposta — busque-o via GET /qr ou o stream GET /qr/stream.
Canal oficial (
whatsapp_official): conexões oficiais NÃO usam QR. Para conectar, informe as credenciais da WABA viaPOST /v1/instances/{instanceId}/official/credentials(abaixo) — a validação contra a Graph API já transiciona a conexão paraCONNECTED. Oconnectnesse canal apenas revalida as credenciais existentes.
GET/v1/instances/{instanceId}/official/credentials#
Estado (mascarado) das credenciais da conexão oficial (canal whatsapp_official
/ Meta Cloud API). O token nunca é retornado — só o hint dos últimos 4
caracteres. 400 se a conexão não estiver no canal oficial.
Auth: Owner, Admin
Resposta 200:
{
"configured": true,
"waba_id": "102290129340398",
"phone_number_id": "106540352242922",
"token_hint": "9876",
"status": "CONNECTED"
}
POST/v1/instances/{instanceId}/official/credentials#
Credencia uma conexão oficial: valida o access_token + phone_number_id
contra a Graph API da Meta, armazena o token cifrado (AES-GCM), e
transiciona a conexão para CONNECTED — sem QR. Requer META_CLOUD_ENABLED=true
no ambiente. Só aceito em conexões do canal whatsapp_official.
Auth: Owner, Admin
Request:
{
"waba_id": "102290129340398",
"phone_number_id": "106540352242922",
"access_token": "EAAG...token-permanente-da-WABA"
}
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
phone_number_id |
string | sim | ID Graph do número de telefone business (NÃO o número de exibição) |
access_token |
string | sim | Token de acesso permanente da WABA (system user) |
waba_id |
string | não | ID da WhatsApp Business Account (necessário para gerenciar templates) |
Resposta 200: estado mascarado (mesmo shape do GET) com
display_phone_number, verified_name e quality_rating do número validado.
Erros: 400 META_CREDENTIALS_INVALID (token/número rejeitado pela Graph
API ou campos ausentes), 503 SERVICE_UNAVAILABLE (adapter meta_cloud não
configurado no ambiente).
O GET das credenciais também retorna reauth_required (bool): quando o
token da WABA é rejeitado pela Graph em uma operação subsequente (token expirado/
revogado — classe auth), a conexão é segurada para reautorização (status
DISCONNECTED), o evento official.reauth_required é emitido, e o Console
mostra o banner "reconecte com a Meta". Reautorizar = novo Embedded Signup ou
novo token via POST .../official/credentials.
Embedded Signup (onboarding self-service — canal oficial)#
Onboarding de uma WABA do cliente sem colar token: o Console abre o diálogo
Embedded Signup da Meta (FB JS SDK), e o backend troca o code pelo token de
negócio do cliente server-side (o token nunca passa pelo browser), assina o
app nos webhooks da WABA e cria a conexão já CONNECTED. Requer o app
configurado com Embedded Signup (META_APP_ID + META_APP_SECRET +
META_EMBEDDED_SIGNUP_CONFIG_ID) — disponível só após o App Review da Meta.
GET /v1/meta/embedded-signup/config#
Config pública, não-secreta que o Console usa para renderizar o botão
"Conectar com a Meta". app_id + config_id são identificadores públicos do
FB JS SDK; o app_secret NUNCA é exposto.
Resposta 200:
{ "enabled": true, "app_id": "1374719154535886", "config_id": "1234567890", "graph_version": "v21.0" }
enabled=false (qualquer um de app_id/app_secret/config_id ausente) → o Console
esconde o botão.
POST /v1/instances/{instanceId}/official/embedded-signup#
Auth: Owner, Admin. Só aceito em conexões whatsapp_official.
Request:
{ "code": "<oauth code do FB JS SDK>", "waba_id": "102290129340398", "phone_number_id": "106540352242922" }
Fluxo server-side: troca code → token de negócio do cliente; assina o app nos
webhooks da WABA (best-effort); valida o token contra a Graph; persiste cifrado;
transiciona para CONNECTED. Resposta 200: mesmo shape mascarado do
GET .../official/credentials.
Erros: 400 META_CREDENTIALS_INVALID (code inválido/expirado, ou campos
ausentes), 503 SERVICE_UNAVAILABLE (Embedded Signup não configurado no
ambiente).
GET/v1/instances/{instanceId}/official/usage (metering)#
Contagem de mensagens/conversas por conexão oficial nos últimos period_days
(default 30; query ?period_days=N, 1–365). Base para pricing comercial. Só
aceito em conexões whatsapp_official.
Resposta 200:
{
"instance_id": "...", "channel": "whatsapp_official", "period_days": 30,
"messages_sent": 1240, "messages_received": 980, "templates_sent": 310,
"conversations": 214
}
conversations = chats distintos (remote_jid) tocados no período — um
proxy para as conversas de 24h que a Meta fatura (a contagem autoritativa
vem dos relatórios da própria Meta). O GET /v1/usage/{companyId} também
ganha uma seção usage.official (rollup por conexão + totais) quando a empresa
tem conexões oficiais.
GET/v1/instances/{instanceId}/official/insights (custo, volume e qualidade)#
Painel consolidado da WABA (WhatsApp Business Management API) da conexão
oficial: qualidade/tier do número, volume enviado/entregue e custo por categoria
de conversa. Janela ?days=N (default 30, limitado a 1–90). Só aceito em
conexões whatsapp_official com credenciais (incluindo waba_id).
Cada bloco é best-effort: se uma das consultas à Meta falhar, o bloco fica
vazio e o motivo entra em warnings — a resposta continua 200.
Resposta 200:
{
"period": { "start": 1760000000, "end": 1762592000, "days": 30 },
"quality": {
"quality_rating": "GREEN", "messaging_limit_tier": "TIER_1K",
"name_status": "APPROVED", "display_phone_number": "+55 41 9999-9999",
"verified_name": "Minha Empresa"
},
"messaging": {
"sent": 1240, "delivered": 1198,
"points": [ { "start": 1760000000, "end": 1760086400, "sent": 40, "delivered": 39 } ]
},
"cost": {
"total_cost": 12.34, "total_conversations": 214,
"by_category": [ { "category": "MARKETING", "conversations": 120, "cost": 9.10 } ],
"points": [ { "start": 1760000000, "end": 1760086400, "conversation": 7, "cost": 0.42,
"conversation_category": "MARKETING", "conversation_type": "REGULAR" } ]
},
"warnings": ["cost: ..."]
}
GET/v1/instances/{instanceId}/official/template-analytics (funil por template)#
Funil de entrega por template (enviado → entregue → lido → cliques em botão),
granularidade diária. Query: ?days=N (1–90, default 30) e
?template_ids=id1,id2 (opcional; sem ele, todos os templates). Exige que a
WABA tenha o template analytics habilitado na Meta (opt-in único); sem isso
a Meta recusa e a API devolve o erro da Graph (4xx).
Resposta 200:
{
"period": { "start": 1760000000, "end": 1762592000, "days": 30 },
"data_points": [
{ "template_id": "1234567890", "start": 1760000000, "end": 1760086400,
"sent": 50, "delivered": 49, "read": 31,
"clicked": [ { "type": "quick_reply_button", "button_content": "Quero saber mais", "count": 12 } ] }
]
}
GET/v1/instances/{instanceId}/marketing-optouts (opt-out de marketing)#
Estado de opt-out de marketing por contato numa conexão oficial, aprendido do
webhook user_preferences da Meta (o contato tocou "parar/retomar promoções").
O próprio caminho de envio já respeita esse estado; esta rota é a visão do
operador. Query: ?opted_out=true filtra só quem está fora. Até 500 itens,
mais recentes primeiro.
Resposta 200:
{
"items": [
{ "phone": "5541999999999", "remote_jid": "5541999999999@s.whatsapp.net",
"opted_out": true, "category": "marketing", "updated_at": "2026-11-10T14:03:00Z" }
],
"count": 1
}
Templates da WABA (canal oficial)#
Gerenciamento dos message templates (HSM) da conexão oficial — proxy da Graph
API ({waba_id}/message_templates). Só aceito em conexões whatsapp_official
com credenciais (incluindo waba_id) configuradas.
| Método | Rota | Descrição |
|---|---|---|
GET |
/v1/instances/{id}/templates |
Lista templates com status (APPROVED/PENDING/REJECTED) |
POST |
/v1/instances/{id}/templates |
Cria template (name, language, category, components) — entra PENDING na aprovação da Meta |
DELETE |
/v1/instances/{id}/templates/{name} |
Remove o template pelo nome |
POST |
/v1/instances/{id}/official/send-template |
Envia um template HSM aprovado (única forma de ABRIR uma conversa fora da janela de 24h) |
POST |
/v1/instances/{id}/official/send-interactive |
Envia mensagem interativa nativa (reply buttons / lista / CTA URL / pedido de localização / address / Flow) — ver seção abaixo |
POST |
/v1/instances/{id}/official/send-product |
Commerce: envia UM produto do catálogo — ver seção Commerce abaixo |
POST |
/v1/instances/{id}/official/send-product-list |
Commerce: envia até 30 produtos em até 10 seções |
POST |
/v1/instances/{id}/official/send-catalog |
Commerce: envia o catálogo inteiro como um card |
Janela de atendimento de 24h (canal oficial). Fora da janela (nenhuma
mensagem inbound do contato nas últimas 24h), envios free-form (texto/mídia)
são recusados com 409 OUTSIDE_SERVICE_WINDOW — só templates aprovados passam. A
janela abre a cada mensagem recebida do contato (sinal lido da tabela messages,
escrita sincronamente pelo webhook ingest). A válvula de escape é
POST /v1/instances/{id}/official/send-template (abaixo), NÃO
POST /v1/instances/{id}/messages/template (esse é o template hidratado do whatsmeow — não-
oficial — e retorna not supported numa conexão meta_cloud). Não-meta_cloud
não têm janela.
POST /v1/instances/{instanceId}/official/send-template#
Envia um template HSM aprovado pela conexão oficial (meta_cloud). É o
único tipo de mensagem que ABRE uma conversa fora da janela de 24h. Entra pelo
MESMO pipeline Asynq dos outros envios (idempotência, throttle, message_id
UUID pré-gerado, emitSent) e retorna 202.
Auth: Owner, Admin. Só aceito em conexões whatsapp_official; numa conexão
não-oficial retorna 400. Requer header Idempotency-Key.
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
to |
string | sim | Número do destinatário (E.164 / normalização BR aplicada) |
template_name |
string | sim | Nome do template aprovado (ex.: hello_world) |
language |
string | sim | Código de idioma do template (ex.: pt_BR, en_US) |
components |
array (raw JSON) | não | template.components da Cloud API (parâmetros de header/body/botão); omitir para template sem variáveis |
POST /v1/instances/{id}/official/send-template
Idempotency-Key: <uuid>
{
"to": "5541999998888",
"template_name": "welcome_v1",
"language": "pt_BR",
"components": [
{ "type": "body", "parameters": [ { "type": "text", "text": "Ana" } ] }
]
}
202 Accepted: { "status": "queued", "message_id": "<UUID>", "task_id": "...", "idempotency_key": "..." }
— o message_id é o mesmo UUID emitido no webhook message.sent. O wamid da
Meta é gravado no send para correlacionar os statuses (delivered/read).
POST /v1/instances/{instanceId}/official/send-interactive#
Envia uma mensagem interativa nativa da Cloud API pelo canal oficial:
reply buttons, lista, botão CTA URL, pedido de localização, endereço (address)
ou Flow (nfm). Um pipeline genérico cobre os 6 tipos — o caller monta o
objeto interactive no schema da Cloud API e a Catcher entrega pelo mesmo
pipeline Asynq (idempotência, throttle, message_id UUID, emitSent).
Auth: Todos autenticados. Só aceito em conexões whatsapp_official
(400 numa não-oficial). Requer header Idempotency-Key. Sujeito à janela de
24h (409 OUTSIDE_SERVICE_WINDOW fora dela — reengaje com template).
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
to |
string | sim | Destinatário (E.164 / normalização BR aplicada) |
kind |
string | não | Dica do tipo: button, list, cta_url, location_request, address, flow |
interactive |
object (raw JSON) | sim | O objeto interactive da Cloud API (type + header/body/footer + action), montado pelo caller |
Exemplos dos tipos validados ao vivo (2026-07-19, render + interação em device real):
// Reply buttons (até 3) — o tap volta como button_reply.received (detail com a seleção)
{ "to": "5541999998888", "kind": "button", "interactive": {
"type": "button",
"body": { "text": "Confirma o agendamento?" },
"action": { "buttons": [
{ "type": "reply", "reply": { "id": "opt_sim", "title": "Sim" } },
{ "type": "reply", "reply": { "id": "opt_nao", "title": "Não" } } ] } } }
// Lista/menu (até 10 rows em seções)
{ "to": "5541999998888", "kind": "list", "interactive": {
"type": "list",
"header": { "type": "text", "text": "Menu" },
"body": { "text": "Escolha uma opção" },
"action": { "button": "Ver opções", "sections": [
{ "title": "Planos", "rows": [
{ "id": "row_start", "title": "Plano Start", "description": "Para começar" } ] } ] } } }
// Botão CTA com link
{ "to": "5541999998888", "kind": "cta_url", "interactive": {
"type": "cta_url",
"body": { "text": "Conheça a Catcher" },
"action": { "name": "cta_url", "parameters": {
"display_text": "Abrir site", "url": "https://catcher.one" } } } }
// Pedido de localização — o toque abre o "compartilhar localização" do WhatsApp
{ "to": "5541999998888", "kind": "location_request", "interactive": {
"type": "location_request_message",
"body": { "text": "Compartilhe sua localização 📍" },
"action": { "name": "send_location" } } }
202 Accepted: mesmo envelope do send-template (message_id UUID +
task_id + idempotency_key).
Retornos (o que volta pelo webhook/SSE quando o contato interage):
| Interação do contato | Evento(s) emitido(s) |
|---|---|
| Tap em reply button / item de lista | message.received (type button_reply/list_reply, content = label tocado) com a seleção estruturada em data.detail (reply_type, selected_id, display_text/title/description) |
| Submit de um Flow | message.received (type interactive_reply) com data.detail.reply_type: "interactive_reply" + o JSON de resposta do formulário em detail.native_flow_params_json |
Resposta a location_request |
message.received type location com latitude/longitude (float), location_address (quando o lugar é nomeado), nome em content, e quoted_msg_id = UUID do pedido (correlação pedido→resposta) |
| Clique no CTA URL | Nenhum evento (o link abre no browser do contato — sem reply) |
Carrossel: enviável via template aprovado com componentes
carousel(POST .../official/send-template) — não pelo endpoint genérico. Flow: requer um Flow publicado no Flow Builder da WABA (ointeractivereferenciaflow_id/flow_cta). Address message: disponibilidade restrita por região pela Meta (pode não renderizar no BR).
Commerce — enviar produto, lista de produtos e catálogo (canal oficial)#
Três endpoints tipados para vender dentro da conversa. Os três são
mensagens interactive na Cloud API, então usam o MESMO pipeline do
send-interactive (idempotência, throttle, message_id UUID, emitSent) — a
diferença é que a Catcher monta o objeto da Meta e valida os limites dele
localmente, então um envio malformado falha com 400 legível em vez de um erro
cru da Graph API depois do round-trip.
Pré-requisitos (do lado do cliente, não da Catcher): o catálogo é criado no Commerce Manager do cliente e conectado à WABA dele; o número precisa estar com catálogo visível (e carrinho ligado, se quiser receber pedido). A Catcher nunca hospeda nem curadoria catálogo — a Commerce Policy da Meta é do comerciante.
Auth: Owner, Admin. Só em conexões whatsapp_official (400 na
não-oficial). Requer Idempotency-Key. Sujeito à janela de 24h
(409 OUTSIDE_SERVICE_WINDOW fora dela — fora da janela, use o template MPM).
Retorno: 202 com o mesmo envelope do send-template.
Limites da Meta validados localmente (falha 400 antes de ir pra Graph):
header ≤60 caracteres, body ≤1024, footer ≤60, título de seção ≤24,
≤10 seções e ≤30 produtos por lista. Contagem em caracteres, não bytes.
POST /v1/instances/{instanceId}/official/send-product#
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
to |
string | sim | Destinatário (E.164 / normalização BR aplicada) |
catalog_id |
string | sim | ID do catálogo no Commerce Manager |
product_retailer_id |
string | sim | SKU do produto (content ID no catálogo) |
body |
string | não | Texto acima do card |
footer |
string | não | Rodapé |
{ "to": "5541999998888", "catalog_id": "SEU_CATALOG_ID",
"product_retailer_id": "SKU-CAMISA-M",
"body": "Essa é a camisa que você pediu", "footer": "Entrega em até 2 dias úteis" }
POST /v1/instances/{instanceId}/official/send-product-list#
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
to |
string | sim | Destinatário |
catalog_id |
string | sim | ID do catálogo |
header |
string | sim | Cabeçalho — a Meta só aceita header de texto aqui |
body |
string | sim | Corpo da mensagem |
footer |
string | não | Rodapé |
sections[] |
array | sim | 1 a 10 seções, somando no máximo 30 produtos |
sections[].title |
string | sim quando há mais de 1 seção | Título da seção |
sections[].product_retailer_ids[] |
array | sim | SKUs da seção (≥1) |
{ "to": "5541999998888", "catalog_id": "SEU_CATALOG_ID",
"header": "Nossa vitrine", "body": "Escolha os produtos e monte seu carrinho",
"sections": [
{ "title": "Camisas", "product_retailer_ids": ["SKU-CAMISA-M", "SKU-CAMISA-G"] },
{ "title": "Acessórios", "product_retailer_ids": ["SKU-BONE"] } ] }
Silêncio da Meta: um
product_retailer_idque não existe no catálogo é descartado silenciosamente pela Meta (a mensagem vai, o item some). A Catcher valida forma e limites; a existência do SKU é responsabilidade do catálogo do cliente.
POST /v1/instances/{instanceId}/official/send-catalog#
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
to |
string | sim | Destinatário |
body |
string | sim | Texto do card |
footer |
string | não | Rodapé |
thumbnail_product_retailer_id |
string | não | SKU cuja imagem estampa o card (default: primeiro item do catálogo) |
{ "to": "5541999998888", "body": "Veja nosso catálogo completo",
"footer": "Entrega para todo o Brasil", "thumbnail_product_retailer_id": "SKU-CAMISA-M" }
O retorno: o pedido do cliente#
Quando o contato monta o carrinho e envia, chega um message.received type
order (order.received sob o dialeto específico; evento operacional — sem
linha de mensagem armazenada, message_ids: []) com quais produtos foram
pedidos em data.detail.items. Ver a seção do evento em Webhooks.
POST/v1/meta/webhook (ingest oficial — chamado pela Meta)#
Endpoint público que recebe as notificações (mensagens + statuses) da
WhatsApp Cloud API. A Meta chama sem autenticação; a assinatura HMAC
X-Hub-Signature-256 (sobre META_APP_SECRET) é a autenticação. Cada payload
é roteado à conexão dona pelo metadata.phone_number_id, e alimenta o MESMO
pipeline de eventos dos outros backends: message.received (inclusive
reactions, type reaction), message.delivered,
message.read, message.delivery_failed — com
contrato UUID (nunca o wamid cru) e mídia re-hospedada no R2 (nunca URL de CDN
da Meta). O GET /v1/meta/webhook responde o handshake hub.challenge da Meta
(verify token META_WEBHOOK_VERIFY_TOKEN). Um erro de processamento SEMPRE
retorna 200 para evitar a tempestade de re-entrega da Meta.
Eventos operacionais do canal oficial (além do ciclo de mensagem acima):
| Evento | Quando | Payload |
|---|---|---|
official.template_status |
Um template da WABA mudou de status de aprovação | template_name, template_id, language, status (APPROVED/REJECTED/PAUSED/DISABLED/PENDING), reason, timestamp |
official.quality_update |
Mudou a qualidade/tier do número | display_phone_number, event, current_limit, quality_rating (GREEN/YELLOW/RED), timestamp |
official.reauth_required |
O token da WABA foi rejeitado (expirado/revogado) — a conexão é segurada para reautorização | reason, graph_code (ex.: 190), timestamp |
official.automatic_event |
A Meta detectou que uma conversa nascida de anúncio Click-to-WhatsApp virou lead ou compra (webhook field automatic_events) |
phone, from, event_name (LeadSubmitted/Purchase), ctwa_clid, currency, value_1000 (só em Purchase), timestamp |
official.automatic_eventé atribuição, não commerce. Octwa_clidé o MESMO que já chega noad_contextdomessage.received— junte os dois e você fecha o loop anúncio → conversa → resultado, que é o buraco negro de quem roda CTWA. Requer que o fieldautomatic_eventsesteja subscrito no App Dashboard da Meta. Indisponível na UE, Reino Unido e Japão (Brasil OK).
POST/v1/instances/{instanceId}/disconnect#
Desconecta a instância do WhatsApp (mantem a sessão para reconexao).
Auth: Owner, Admin
Semântica: também pode ser usado para parar uma tentativa em andamento (CONNECTING, QR_PENDING, PAIRING). A API persiste imediatamente status=DISCONNECTED, desired_state=DISCONNECTED e libera a instância para reconectar ou excluir sem ficar presa em retry; o teardown do worker continua de forma assíncrona quando aplicável.
Resposta 200: Objeto de instância atualizado.
POST/v1/instances/{instanceId}/restart#
Reinicia a conexão da instância.
Auth: Owner, Admin
Resposta 200: Objeto de instância atualizado.
POST/v1/instances/{instanceId}/refresh-session#
Tenta recuperar uma sessão wwebjs já pareada sem QR, do passo mais leve ao mais forte: reconectar o socket, recarregar a WhatsApp Web e, por último, reiniciar a sessão — sempre no mesmo IP. Síncrono: pode levar alguns minutos.
Auth: Owner, Admin · Provider: só wwebjs (400 SESSION_REFRESH_NOT_SUPPORTED nos demais)
Resposta 200:
{ "recovered": true, "rung": 2, "gave_up": false, "reason": "manual", "final_status": "CONNECTED" }
reason |
Significado |
|---|---|
manual |
A escada rodou; recovered diz se a sessão voltou e rung em qual passo |
awaiting_pairing |
A instância está esperando o pareamento por QR e nunca ficou pronta — não há sessão a recuperar. Nada foi executado, para não trocar o QR que o celular pode estar lendo. Escaneie o QR |
cooldown |
Uma atualização acabou de rodar (ou ainda está rodando); tente de novo em alguns segundos |
no_runner |
Não há sessão ativa no worker |
POST/v1/instances/{instanceId}/rotate-proxy#
Rejeita o IP dedicado atual da instância no pool/broker e vincula um IP limpo.
Auth: Owner, Admin
Uso: ferramenta operacional para instância presa por falha de rede/proxy antes de reconectar. A instância deve reconectar manualmente ou pelo reconciler para usar o novo IP.
Resposta 200:
{
"rotated": true,
"new_ip": "200.160.47.162"
}
| Campo | Tipo | Descricao |
|---|---|---|
rotated |
boolean | Confirma que a troca foi aplicada |
new_ip |
string | Novo IP dedicado vinculado à instância |
POST/v1/instances/{instanceId}/logout#
Faz logout do WhatsApp e apaga a sessão. A instância precisara parear novamente.
Auth: Owner, Admin
Resposta 200: Objeto de instância atualizado.
POST/v1/instances/{instanceId}/migrate-provider#
Troca o provider da instância na própria instância: hoje, whatsmeow → wwebjs (WhatsApp Web). O instance_id não muda, então mensagens, mídias, contatos, eventos e webhooks continuam ligados a ela, e o IP de proxy dedicado é mantido (a sessão nova nasce no mesmo IP).
A troca é um pareamento novo: se a instância ainda tem número pareado (conectada ou não), o aparelho atual é desvinculado (logout) e a troca só acontece depois que o worker confirma; se não confirmar a tempo, nada muda (504 PROVIDER_MIGRATION_LOGOUT_TIMEOUT). Para uma linha offline cujo desvínculo o worker não confirmou, o operador pode repetir com "force": true (nunca vale para uma linha conectada). Depois a instância fica DISCONNECTED com desired_state=DISCONNECTED, esperando o operador chamar POST .../connect e escanear o QR Code. Na sincronização de histórico do WhatsApp Web, mensagens já gravadas não duplicam (a deduplicação é pelo id do WhatsApp). Mídias já salvas continuam acessíveis; encaminhar ou baixar de novo mídia de mensagens antigas pode falhar, porque o WhatsApp Web só alcança o que ainda está no aparelho. Emite instance.provider_changed.
Auth: Superadmin (o provider é interno; 403 FORBIDDEN para os demais). Uma migração por vez por instância.
Request:
{ "provider": "wwebjs", "force": false }
Resposta 200:
{ "instance_id": "9c8ffc46-91cf-458b-b9cd-4f94eaa9003a", "from": "whatsmeow", "provider": "wwebjs", "status": "DISCONNECTED", "previous_device_unlinked": true, "next": "connect" }
previous_device_unlinked: false = a instância já estava desconectada; o aparelho antigo pode continuar listado no celular em Aparelhos conectados e pode ser removido por lá.
| Erro | Quando |
|---|---|
400 PROVIDER_MIGRATION_UNSUPPORTED |
destino diferente de wwebjs, ou instância que não é whatsmeow |
409 PROVIDER_MIGRATION_NOT_NEEDED |
a instância já usa wwebjs |
409 PROVIDER_MIGRATION_BUSY |
instância conectando / esperando QR / pareando, ou mudou durante a migração |
504 PROVIDER_MIGRATION_LOGOUT_TIMEOUT |
o aparelho atual não confirmou o logout a tempo; nada foi trocado (linha offline: repetir com force: true) |
403 FORBIDDEN |
quem chamou não é superadmin |
401 UNAUTHORIZED |
sem autenticação |
404 INSTANCE_NOT_FOUND |
instância inexistente ou de outra empresa |
502 SERVICE_DOWN / 503 SERVICE_DOWN |
não foi possível pedir o desvínculo do aparelho (fila indisponível); nada foi trocado |
Uma linha offline que ainda tem número pareado sempre termina em 504 na primeira chamada (o worker só desvincula uma sessão que ele está segurando) — repita com force: true. Nesse caso a sessão antiga do whatsmeow não é apagada do disco do worker; ela fica inerte (o worker nunca restaura uma linha que não é whatsmeow).
POST/v1/instances/{instanceId}/history/import#
Solicita importação manual de histórico antigo. Em instâncias whatsmeow, a chamada e assincrona: o endpoint pede ao WhatsApp uma página de histórico por conversa conhecida; as mensagens retornam depois em eventos history.sync e são gravadas na tabela messages. Em instâncias wwebjs, o endpoint executa um replay recente e limitado via WhatsApp Web (chat.syncHistory() + fetchMessages) e grava as mensagens disponíveis imediatamente. Em ambos os providers, mensagens novas importadas emitem message.received/message.sent por padrão, com historical=true e history_source="history_import", e o histórico salvo fica disponível em GET /v1/instances/{instanceId}/chats e GET /v1/instances/{instanceId}/chats/{chatId}/messages.
Auth: Owner, Admin
Request (opcional):
{
"chat_jid": "554137984905@s.whatsapp.net",
"limit": 50,
"window_seconds": 604800,
"suppress_events": false
}
| Campo | Tipo | Obrigatório | Descricao |
|---|---|---|---|
chat_jid |
string | não | Quando informado, solicita histórico apenas desse chat. Vazio = uma página para cada chat com mensagem ancora já salva |
limit |
int | não | Mensagens por chat. Padrão 50, máximo 100 |
since |
int | não | Unix timestamp inferior para wwebjs. Quando informado, tem prioridade sobre window_seconds |
window_seconds |
int | não | Janela recente para wwebjs quando since não foi informado. Padrão do roteador: 7 dias para instâncias sem ancora local |
suppress_events |
bool | não | Padrão false. Quando true, grava as mensagens históricas sem emitir os eventos message.received/message.sent por mensagem. O resumo history.sync/history.import_* continua podendo ser emitido |
Resposta 200:
{
"instance_id": "84c2e480-...",
"status": "requested",
"limit": 50,
"requested_chats": 3,
"requested_messages": 150
}
| Campo | Tipo | Descricao |
|---|---|---|
status |
string | requested quando ao menos um pedido foi enviado ao WhatsApp; skipped quando não havia ancora de mensagem |
chat_jid |
string | Echo do chat alvo quando a request especificou chat_jid |
requested_chats |
int | whatsmeow: quantos chats receberam pedido ON_DEMAND; wwebjs: quantos chats foram varridos na janela |
requested_messages |
int | whatsmeow: máximo teorico solicitado (requested_chats * limit); wwebjs: mensagens novas persistidas |
skipped_chats |
int | Chats que tinham ancora mas o pedido ao WhatsApp falhou |
message |
string | Motivo quando status=skipped |
Notas:
- Em
whatsmeow, a importação manual depende de uma mensagem ancora já existente no histórico local. Para conexões novas, ohistory.syncautomático do WhatsApp agora também e persistido e normalmente cria essas ancoras. - Em
wwebjs, uma instância recém-pareada pode não ter ancora local; nesse caso, omitirsinceewindow_secondsusa uma janela recente padrão de 7 dias. O import e limitado ao que o WhatsApp Web expõe para a sessão. - Mensagens históricas são salvas com
source="phone"para inbound esource="external"para outbound vindo do celular/WhatsApp Web. Por padrão elas também disparammessage.received/message.sent, entram no histórico de eventos/webhooks e carregamhistorical=true+history_source="history_import"para o consumidor distinguir replay/backfill de tráfego ao vivo.
historicalresponde "isso é velho?", não "que caminho entregou" (desde 2026-09-20). Quando o worker reconecta (deploy, restart, queda de rede), ele busca o que chegou enquanto esteve fora. Esse backlog recente é entregue como tráfego AO VIVO —message.received/message.sentsemhistorical— porque é uma mensagem de verdade que você precisa tratar, apenas recebida com atraso. Só o que é mais antigo que a janela de tolerancia (6h por padrao) sai marcadohistorical=true. A importação EXPLÍCITA de histórico (POST /history/import, que pede dias) continua semprehistorical=true.Antes disso, todo backlog de reconexao vinha marcado como historico: um consumidor que FILTRE historico — o correto, pra nao reprocessar conversa velha — perderia silenciosamente mensagens enviadas durante qualquer restart do worker (~1 min).
- No
whatsmeow, o retorno do WhatsApp continua sendo resumido porhistory.sync; nowwebjs, a resposta 200 já traz os contadores do replay. Leia as mensagens importadas pelos endpoints de chat/mensagens.
Erros:
400- JSON inválido404- Instância não encontrada400- Instância não conectada ou falha ao solicitar histórico ao worker
DELETE/v1/instances/{instanceId}#
Remove a instância permanentemente, mesmo se ela estiver CONNECTED, CONNECTING ou QR_PENDING. A API interrompe a conexão/tentativa e soft-deleta a linha imediatamente; o teardown do worker e a liberação do proxy dedicado continuam best-effort/assíncronos conforme o provider, sem exigir um disconnect manual prévio.
Estados da linha: DELETING é só o marcador em andamento (tarefas em voo ignoram a linha); a exclusão termina sempre em status=DELETED com deleted_at preenchido, numa única escrita — mesmo quando o worker soft-deletou a linha antes da API. Linhas antigas que ficaram em DELETING com deleted_at (exclusões anteriores a 2026-11-12) são fechadas como DELETED pela reconciliação idempotente que a API roda no boot, em todos os schemas de tenant.
Auth: Owner, Admin
Resposta 204: Sem corpo.
GET/v1/instances/{instanceId}/usage#
Retorna contadores de mensagens da instância nas últimas 24h.
Auth: Owner, Admin, Agent
Resposta 200:
{
"messages_today": 128,
"messages_sent_today": 80,
"messages_received_today": 48,
"delivered_today": 76,
"failed_today": 4
}
| Campo | Tipo | Descricao |
|---|---|---|
messages_today |
int | Total enviadas + recebidas nas últimas 24h |
messages_sent_today |
int | Mensagens outbound nas últimas 24h |
messages_received_today |
int | Mensagens inbound nas últimas 24h |
delivered_today |
int | Outbound que chegaram ao WhatsApp (status sent/delivered/read/played) |
failed_today |
int | Outbound com falha (status failed ou failed_at preenchido) |
Erros:
400-instanceIdausente404/500- instância/tenant DB indisponível
GET/v1/instances/{instanceId}/throughput#
Retorna 24 buckets horarios de atividade outbound nas últimas 24h (alinhados a hora UTC, sempre em ordem cronologica; horas sem atividade retornam zeros).
Auth: Owner, Admin, Agent
Resposta 200:
{
"buckets": [
{ "hour": "2026-05-16T13:00:00Z", "sent": 12, "delivered": 11, "failed": 1 }
]
}
| Campo | Tipo | Descricao |
|---|---|---|
hour |
string | Início do bucket (RFC3339, UTC) |
sent |
int | Mensagens outbound criadas nessa hora |
delivered |
int | Outbound que chegaram ao WhatsApp (status além de queued, sem falha) |
failed |
int | Outbound com falha |
Erros:
400-instanceIdausente500- tenant DB indisponível / falha ao carregar throughput
GET/v1/instances/{instanceId}/connection-timeline#
Retorna uma serie cronologica de segmentos de conexão/desconexao das últimas 24h (default) ou 7 dias.
Auth: Owner, Admin, Agent
Query Parameters:
| Parametro | Tipo | Descricao |
|---|---|---|
window |
string | 7d para janela de 7 dias. Omitido = 24h |
Resposta 200:
{
"window_start": "2026-05-16T13:00:00Z",
"window_end": "2026-05-17T13:00:00Z",
"segments": [
{ "start": "2026-05-16T13:00:00Z", "end": "2026-05-17T13:00:00Z", "status": "connected" }
]
}
| Campo | Tipo | Descricao |
|---|---|---|
segments[].status |
string | connected, disconnected ou unknown |
Erros:
400-instanceIdausente500- tenant DB indisponível / falha ao carregar timeline
GET/v1/instances/{instanceId}/latency#
Retorna 24 buckets horarios de latencia de envio -> confirmação (p50, p95) para mensagens outbound das últimas 24h.
Auth: Owner, Admin, Agent
Resposta 200:
{
"buckets": [
{ "hour": "2026-05-16T13:00:00Z", "count": 14, "p50_ms": 820, "p95_ms": 2400 }
]
}
| Campo | Tipo | Descricao |
|---|---|---|
hour |
string | Início do bucket (RFC3339, UTC) |
count |
int | Mensagens com receipt nesse bucket |
p50_ms |
int | Latencia mediana em ms (sent_at -> primeiro receipt: delivered/read/played) |
p95_ms |
int | Latencia p95 em ms |
Erros:
400-instanceIdausente500- tenant DB indisponível / falha ao carregar latencia
GET/v1/instances/{instanceId}/logs#
Retorna linhas de log filtradas e escopadas a instância (e a empresa autenticada). Util para diagnostico — owners/admins veem porque suas mensagens não persistem sem precisar de acesso superadmin.
Auth: Owner, Admin, Agent
Query Parameters:
| Parametro | Tipo | Descricao |
|---|---|---|
limit |
int | Linhas retornadas (default 200, máximo 1000) |
level |
string | Filtro de nivel (error, warn, info...) |
contains |
string | Filtro de substring |
Resposta 200:
{
"instance_id": "84c2e480-...",
"company_id": 7,
"total": 1240,
"showing": 200,
"limit": 200,
"lines": ["{\"level\":\"info\",...}"]
}
Erros:
400-instanceIdausente404- arquivo de log não encontrado503- diretorio de log não configurado
GET/v1/instances/{instanceId}/health#
Retorna o snapshot de saúde da instância — score, contadores cumulativos por tipo de evento, meta_paired_at e os eventos de proxy mais recentes escopados a essa instância.
Auth: Owner, Admin, Agent
Resposta 200:
{
"instance_id": "84c2e480-...",
"name": "Atendimento Principal",
"status": "CONNECTED",
"desired_state": "CONNECTED",
"phone": "554137984905",
"health_score": 92,
"health_score_updated_at": "2026-05-17T12:00:00Z",
"meta_paired_at": "2026-05-10T09:00:00Z",
"last_activity_at": "2026-05-17T12:30:00Z",
"last_seen": "2026-05-17T12:30:05Z",
"connected_at": "2026-05-10T09:01:00Z",
"disconnected_at": null,
"proxy_ip_id": 42,
"totals": {
"connects": 5,
"disconnects": 4,
"qr_cycles": 2,
"qr_timeouts": 0,
"connect_failures": 1,
"cooldowns_hit": 0,
"bans": 0
},
"proxy": {
"id": 42,
"ip_address": "200.x.x.x",
"city": "br-saopaulo",
"status": "assigned",
"health_score": 100,
"last_event_at": "2026-05-17T12:00:00Z"
},
"recent_events": []
}
| Campo | Tipo | Descricao |
|---|---|---|
health_score |
int | Score de saúde acumulado da instância |
meta_paired_at |
string/null | Quando a instância foi pareada ao Meta |
totals |
object | Contadores cumulativos por tipo de evento |
proxy |
object | Presente quando a instância tem proxy bound |
recent_events |
array | Eventos de proxy escopados a essa instância (até 50) |
Erros:
400 INVALID_ID-instanceIdausente403 FORBIDDEN- contexto tenant ausente404 INSTANCE_NOT_FOUND- instância não encontrada
GET/v1/instances/{instanceId}/proxy-reputation#
Retorna o status de reputacao (sanitizado) do IP de proxy atualmente vinculado a instância. O score numerico, nomes de provedores e dados de ASN não são expostos — esse e um selo amigavel para o cliente.
Auth: Owner, Admin, Agent
Resposta 200:
{
"status": "ok",
"country": "BR",
"city": "br-saopaulo",
"isp_label": "Internet residencial",
"checks_passed": 4,
"checks_total": 4,
"checked_at": "2026-05-17T10:00:00Z",
"next_check_at": "2026-05-24T10:00:00Z"
}
| Campo | Tipo | Descricao |
|---|---|---|
status |
string | ok, watch, bad, inconclusive ou unknown |
isp_label |
string | Internet residencial, Conexao corporativa, Em rotacao ou Verificando |
checks_passed / checks_total |
int | Contagens genericas de verificacoes |
Instâncias legadas sem proxy retornam
{"status":"unknown"}para o frontend esconder o selo.
Erros:
400 BAD_REQUEST-instanceIdausente404 INSTANCE_NOT_FOUND- instância não encontrada503 SERVICE_UNAVAILABLE- tenant DB indisponível
GET/v1/instances/{instanceId}/qr#
Retorna o QR code atual para parear a instância.
Auth: Owner, Admin
Resposta 200:
{
"qr": "2@abc123...",
"qr_base64": "iVBORw0KGgo...",
"mime_type": "image/png"
}
qrcontem a string raw para gerar localmente;qr_base64contem a imagem PNG do QR em base64. Se a instância não tiver QR pendente, retorna400.
Contrato do QR (idêntico em todos os providers).
qr_base64é sempre base64 PURO — NUNCA inclui o prefixodata:image/png;base64,. Para exibir, o consumidor adiciona o prefixo:<img src="data:image/png;base64,${qr_base64}">.qreqr_base64são atômicos: ou ambos vêm preenchidos juntos, ou ambos vazios — nunca umqrraw sem a imagem correspondente.mime_typeé sempreimage/pngquando há QR. Esse contrato vale igualmente paraGET /qr, o streamGET /qr/streame o SSE de eventos, independentemente do provider da instância (whatsmeow ou wwebjs).
GET/v1/instances/{instanceId}/device#
Retorna telemetria do device pareado no WhatsApp e o fingerprint de saída usado no túnel Meta.
Auth: Owner, Admin
Resposta 200:
{
"jid": "554137984905:1@s.whatsapp.net",
"lid": "123456789@lid",
"platform": "smbi",
"business_name": "Empresa LTDA",
"push_name": "Empresa LTDA",
"device": 1,
"tls_profile": "chrome_124_windows",
"user_agent": "Mozilla/5.0 (...)"
}
| Campo | Tipo | Descricao |
|---|---|---|
jid |
string | JID completo do device pareado |
lid |
string | LID do device, quando disponível |
platform |
string | Classe de device reportada pelo WhatsApp (smbi, smba, iPhone, etc.) |
business_name |
string | Nome business reportado, quando disponível |
push_name |
string | Push name do device |
device |
int | Índice do device atribuido no pareamento |
tls_profile |
string | Perfil uTLS sticky usado pela instância, quando configurado |
user_agent |
string | User-Agent usado pela instância no websocket Meta |
POST/v1/instances/{instanceId}/diagnose#
Executa uma bateria read-only de diagnóstico da instância. Não reconecta, não altera estado e não reinicia sessão.
Auth: Owner, Admin
Resposta 200:
{
"instance_id": "84c2e480-...",
"overall_ok": true,
"started_at": 1741361650,
"duration_ms": 42,
"checks": [
{
"name": "master_db",
"status": "ok"
},
{
"name": "queue_depth",
"status": "skipped",
"detail": "métricas globais de fila visíveis apenas para superadmin"
}
],
"summary": {
"ok": 7,
"warn": 0,
"fail": 0,
"skipped": 3
}
}
Checks possíveis: master_db, tenant_db, redis, instance_row, proxy_binding, instance_state, queue_depth, throttle, recent_messages, recent_events.
Para não-superadmin, métricas globais ou identificadores internos de proxy/fila podem vir como
skippedou redigidos.
GET/v1/instances/{instanceId}/qr/stream#
Stream SSE de QR codes. O servidor envia QR codes conforme são gerados pelo WhatsApp (~20s cada). Quando o usuário escaneia, envia success. A tentativa de pareamento é limitada (estilo WhatsApp Web): após um número finito de QRs sem leitura, o servidor para de gerar QRs e envia um evento stopped — em vez de renovar o QR para sempre. Aí o cliente deve mostrar uma ação "gerar novo QR" e um novo POST /connect reinicia o ciclo.
Auth: Owner, Admin
Headers recomendados para proxies reversos:
X-Accel-Buffering: no(já incluído na resposta)- Desabilitar compressao (
no-gzip) para evitar buffering do SSE
Resposta: Server-Sent Events
event: connected
data: {"instance_id": "84c2e480-..."}
event: code
data: {"event": "code", "qr": "2@abc123...", "qr_base64": "iVBORw0KGgo...", "mime_type": "image/png"}
event: success
data: {"event": "success"}
event: timeout
data: {"event": "timeout"}
event: stopped
data: {"event": "stopped"}
event: error
data: {"event": "error", "message": "descricao do erro"}
| Evento | Descricao |
|---|---|
connected |
Stream iniciado (enviado imediatamente) |
code |
Novo QR code disponível. qr = raw string, qr_base64 = imagem PNG base64 |
success |
Usuário escaneou o QR, instância pareada |
timeout |
Um QR expirou sem leitura (um novo code pode vir em seguida) |
stopped |
A tentativa de pareamento atingiu o limite de QRs e PAROU (estilo WhatsApp Web). Não virão mais QRs neste ciclo. Mostre uma ação "gerar novo QR"; um POST /connect reinicia o ciclo. A instância fica DISCONNECTED até o reconnect manual. |
error |
Erro ao gerar QR |
timeoutvsstopped:timeouté a expiração de UM QR (a sessão pode emitir o próximocode);stoppedé o FIM da tentativa — o servidor parou de forçar QRs e só um novoPOST /connectrecomeça. Tratestoppedcomo terminal: pare de esperarcodee ofereça o botão de gerar novo QR. O número de QRs por tentativa no provider wwebjs é configurável no servidor viaWWEBJS_QR_MAX_REGENS(padrão 5).
Nota: O campo
qr_base64contem a imagem PNG do QR pronta para exibir:<img src="data:image/png;base64,${qr_base64}">. O campoqrcontem a string raw para gerar o QR localmente.
Proxy reverso: Se usar Apache/Nginx como proxy, desabilite compressao e buffering para endpoints SSE (
/qr/streame/events). Sem isso, o browser recebeERR_INCOMPLETE_CHUNKED_ENCODING.
Duração e reconexão: o stream não tem o timeout de 30s das demais rotas (a rota
/v1/admin/instances/{id}/qr/streamdo superadmin segue a mesma regra). O servidor envia um comentário SSE: pinga cada 25s (ignore linhas que começam com:) e encerra o stream após 10 minutos. Um proxy no caminho também pode encerrar a conexão: se o stream fechar semsuccess/stopped, reabra-o (sem novoPOST /connect) — osuccessé publicado uma única vez, no momento do pareamento. Para confirmar sem depender do stream, consulteGET /v1/instances/{id}(status: CONNECTED) ou o eventoconnection.updatecomstatus: connected.Falha antes do QR: se a primeira carga da página falhar antes de qualquer QR, o servidor pausa a tentativa e emite
connection.updatecomstatus: disconnectedereason: connect_failed_no_qr(o stream de QR fica em silêncio). Um novoPOST /connectrecomeça. Erros momentâneos de carregamento da página são retentados automaticamente antes dessa pausa.
POST/v1/instances/{instanceId}/pairing-code#
Gera um código de pareamento (alternativa ao QR code, para parear pelo telefone).
Auth: Owner, Admin
Request:
{
"phone": "554137984905"
}
Resposta 200:
{
"instance_id": "84c2e480-...",
"pairing_code": "SG3M-82AE"
}
Como usar: No WhatsApp do celular, va em Configurações > Aparelhos Conectados > Conectar Aparelho > Conectar com número de telefone. Digite o código recebido.
6.1 Boas Práticas — Fluxo de Conexão (QR dinâmico e Pairing Code)#
Está seção descreve como montar uma tela de conexão rápida, resiliente e com UX parecida com a do Catcher Console. Os usuários que apenas fazem polling em GET /qr ou abrem o SSE sem uma estrategia ficam com telas lentas, QR "parado" e retry manual irritante — todos esses problemas são resolvidos com o padrão abaixo.
Maquina de estados da instância#
CREATED ──POST /connect──► CONNECTING ──► QR_PENDING ──(scan)──► CONNECTED
│ │
▼ ├─(timeout 6 QRs)─► TIMED_OUT
DISCONNECTED │
└─(erro)──────────► DISCONNECTED
| Estado | Significado | Ação do cliente |
|---|---|---|
CREATED |
Instância criada, ainda não tentou conectar | POST /connect para iniciar |
CONNECTING |
Abrindo websocket com WhatsApp, gerando primeiro QR | Abrir /qr/stream e esperar evento code |
QR_PENDING |
Pelo menos um QR já disponível | Exibir QR e aguardar success/timeout |
CONNECTED |
Pareado e recebendo mensagens | Fechar modal, liberar a tela |
TIMED_OUT |
6 QRs expiraram sem leitura (~2min total) | POST /restart e reabrir stream, ou pedir ao usuário para tentar de novo |
DISCONNECTED |
Desconectada (manual ou erro recuperável) | POST /connect para reativar |
LOGGED_OUT |
A Meta encerrou a sessão (conta/aparelho removido, 401/403). Só um novo pareamento por QR revive. Distinta de DISCONNECTED (queda recuperável) e de BANNED (ban temporário com ban_expiry). O número (phone) é preservado para a instância continuar reconhecível. |
POST /connect e reabrir o /qr/stream para reparear |
BANNED |
Banida pelo WhatsApp | Não reconecte automaticamente — veja seção 16, evento instance.banned |
O WhatsApp gera um novo QR a cada ~20 segundos. A tentativa de pareamento é limitada (estilo WhatsApp Web): após um número finito de QRs sem leitura, o servidor para de gerar QRs e envia o evento stopped (a instância fica DISCONNECTED); um POST /connect reinicia o ciclo. Esses QRs chegam automaticamente no /qr/stream via evento code — não existe endpoint "próximo QR". Se você perder esse stream, precisa reiniciar (POST /restart) para reabrir a sessão.
Fluxo recomendado (5 passos)#
1. POST /v1/instances/{id}/connect ◄── dispara QR generation
2. GET /v1/instances/{id}/qr (snapshot) ◄── tela nao fica branca
3. GET /v1/instances/{id}/qr/stream (SSE) ◄── recebe novos QRs + success/timeout
4. GET /v1/instances/{id}/events?events=connection.update (SSE paralelo) ◄── rede de seguranca
5. Ao receber "success" ou CONNECTED: fechar streams, mostrar sucesso
A combinação /qr/stream + /events em paralelo e a diferença entre "funciona na maioria das vezes" e "funciona sempre". Se um proxy reverso engolir o evento success do /qr/stream, a transicao CONNECTING → CONNECTED em connection.update ainda chega pelo /events e você fecha o modal corretamente.
Contrato do /qr/stream#
O servidor envia eventos nomeados SSE conforme a seção GET /v1/instances/{instanceId}/qr/stream. Resumindo:
| Evento | Quando ocorre | Payload relevante | O que fazer |
|---|---|---|---|
connected |
Imediatamente ao abrir | { "instance_id": "..." } |
Confirmar que o stream abriu |
code |
Novo QR disponível (0s, ~20s, ~40s...) | { "qr_base64": "...", "qr": "2@...", "mime_type": "image/png" } |
Renderizar <img src="data:image/png;base64,${qr_base64}"> |
success |
Usuário escaneou o QR | { "event": "success" } |
Fechar modal, emitir toast de sucesso |
timeout |
6 QRs expiraram sem scan | { "event": "timeout" } |
Silent retry ou prompt de "tente de novo" |
error |
Falha na sessão whatsmeow | { "event": "error" } |
Silent retry ou mostrar erro |
Idle timeout: se o stream ficar mais de ~45s sem nenhum evento (nem heartbeat), trate como conexão morta e reabra. Redes móveis e proxies derrubam conexões idle silenciosamente.
Limite de subscribers: cada instância aceita até 20 conexões SSE/WebSocket simultaneas (somando
/qr/stream+/events+ clientes externos). Se você abrir streams em varias abas ou não fizer cleanup, atinge o limite e recebe429 Too Many Requests. Sempre useAbortControllerpara cancelar.
Padrão 1 — Cliente Browser (JS/TS)#
Por que não usar EventSource nativo: o construtor EventSource(url) não aceita headers customizados, logo você não consegue mandar Authorization: Bearer <token>. A solução usada pelo Catcher Console e usar fetch() com ReadableStream, o que permite headers e cancelamento via AbortController.
/**
* Abre o stream SSE de QR code para uma instancia.
* Retorna uma funcao `close()` para abortar o stream limpo.
*/
function openQRStream(instanceId, token, handlers) {
const controller = new AbortController();
const url = `https://api.catcher.one/v1/instances/${instanceId}/qr/stream`;
fetch(url, {
method: 'GET',
signal: controller.signal,
cache: 'no-store',
headers: {
Accept: 'text/event-stream',
Authorization: `Bearer ${token}`,
},
})
.then(async (response) => {
if (!response.ok) throw new Error(`HTTP ${response.status}`);
if (!response.body) throw new Error('stream body unavailable');
const reader = response.body.getReader();
const decoder = new TextDecoder();
let buffer = '';
while (true) {
const { done, value } = await reader.read();
if (done) break;
buffer += decoder.decode(value, { stream: true });
// Eventos SSE sao delimitados por \n\n
let boundary;
while ((boundary = buffer.indexOf('\n\n')) !== -1) {
const raw = buffer.slice(0, boundary);
buffer = buffer.slice(boundary + 2);
if (!raw.trim()) continue;
let eventType = 'message';
let data = '';
for (const line of raw.split('\n')) {
if (line.startsWith(':')) continue; // heartbeat, ignora
if (line.startsWith('event:')) eventType = line.slice(6).trim();
else if (line.startsWith('data:'))
data = data ? `${data}\n${line.slice(5).trim()}` : line.slice(5).trim();
}
try {
handlers.onEvent?.(eventType, data ? JSON.parse(data) : {});
} catch { /* payload malformado, ignora */ }
}
}
handlers.onClose?.();
})
.catch((err) => {
if (err.name === 'AbortError') return;
handlers.onError?.(err);
});
return () => controller.abort();
}
// Uso:
const close = openQRStream(instanceId, token, {
onEvent: (type, data) => {
if (type === 'code') setQR(data.qr_base64);
if (type === 'success') { setConnected(true); close(); }
if (type === 'timeout') silentRetry();
},
onError: () => silentRetry(),
});
Snapshot antes do stream: para evitar o flash de "Gerando QR Code..." quando já existe um QR pendente, chame
GET /qrantes de abrir o stream e renderize o QR imediatamente. O stream entao atualizara o QR a cada 20s.javascript// 1. Snapshot sincrono — tela mostra QR na hora const snap = await fetch(`${api}/instances/${id}/qr`, { headers: auth }).then(r => r.ok ? r.json() : null); if (snap?.qr_base64) setQR(snap.qr_base64); // 2. Em seguida o stream mantem o QR atualizado const close = openQRStream(id, token, handlers);
Alternativa mais simples: se você não quiser escrever o parser manual, use a biblioteca
@microsoft/fetch-event-source. Ela expoe uma APIfetchEventSource()identica aoEventSourcenativo mas com suporte a headers, retry automático eAbortController.
Padrão 2 — Cliente Backend (Node/Go/Python)#
No backend não ha restrição de headers, entao qualquer cliente SSE funciona. Curl e um bom teste rápido:
curl -N \
-H "Authorization: Bearer $TOKEN" \
-H "Accept: text/event-stream" \
"https://api.catcher.one/v1/instances/$INSTANCE_ID/qr/stream"
Exemplo em Go com bufio.Scanner:
req, _ := http.NewRequest("GET", baseURL+"/v1/instances/"+instanceID+"/qr/stream", nil)
req.Header.Set("Authorization", "Bearer "+token)
req.Header.Set("Accept", "text/event-stream")
resp, err := http.DefaultClient.Do(req)
if err != nil { /* ... */ }
defer resp.Body.Close()
scanner := bufio.NewScanner(resp.Body)
var eventType, data string
for scanner.Scan() {
line := scanner.Text()
switch {
case strings.HasPrefix(line, "event:"):
eventType = strings.TrimSpace(strings.TrimPrefix(line, "event:"))
case strings.HasPrefix(line, "data:"):
data = strings.TrimSpace(strings.TrimPrefix(line, "data:"))
case line == "":
// linha em branco = fim do evento
handleQREvent(eventType, data)
eventType, data = "", ""
}
}
Dupla subscricao — /qr/stream + /events em paralelo#
Como rede de seguranca, assine connection.update em paralelo pelo endpoint de eventos da instância. Isso garante que você fecha o modal mesmo se o success do /qr/stream for perdido por qualquer motivo (buffering de proxy, timing de fechamento do stream, etc.).
// Stream de QR (atualiza imagem)
const closeQR = openQRStream(instanceId, token, {
onEvent: (type, data) => {
if (type === 'code') setQR(data.qr_base64);
if (type === 'success') markConnected();
if (type === 'timeout') silentRetry();
},
});
// Stream de eventos da instancia (rede de seguranca)
const closeEvents = openEventStream(instanceId, token, ['connection.update'], (event) => {
if (event.type === 'connection.update' && event.data?.status === 'CONNECTED') {
markConnected();
}
});
function markConnected() {
closeQR();
closeEvents();
showSuccess('Instancia conectada!');
}
Se você já tem uma conexão /events global no seu app (por exemplo, ouvindo message.received o tempo todo), apenas adicione um listener para connection.update durante a tela de conexão — não abra uma segunda conexão para a mesma instância, você gastara uma das 20 slots disponíveis.
Auto-retry silencioso (UX sem friction)#
Usuários abandonam a tela de conexão quando veem "QR expirou, clique para tentar novamente". A tela do Console aplica retry invisível: ao receber timeout ou error, dispara POST /restart e reabre o /qr/stream, mantendo o QR atual visível até o próximo evento code.
const MAX_RETRIES = 10;
let retries = 0;
async function silentRetry() {
if (retries >= MAX_RETRIES) { showTimeoutUI(); return; }
retries += 1;
// pequeno debounce antes de reiniciar
await new Promise(r => setTimeout(r, 1500));
// reinicia a sessao do lado do servidor
await fetch(`${api}/instances/${id}/restart`, {
method: 'POST',
headers: { Authorization: `Bearer ${token}` },
});
// reabre o stream — o QR atual continua visivel ate chegar um novo `code`
closeQR = openQRStream(id, token, handlers);
}
Não apague o QR atual durante o retry — deixe o último QR válido na tela. Se o novo code chegar antes do usuário tentar escanear o anterior, o anterior ainda funciona por alguns segundos. Trocar a imagem so quando chegar o evento code evita flicker.
Pairing Code como alternativa ao QR#
O pairing code e util quando o usuário não tem uma camera funcionando (desktop sem webcam, usuário com dificuldade visual etc.). Tres regras importantes:
- Requer
POST /connectANTES. A chamadaPOST /pairing-codeso funciona se a instância estiver emCONNECTINGouQR_PENDING— caso contrario retorna400 instance not connected, call connect first. Na prática, execute o mesmo fluxo do QR e apenas troque a interface. - Código expira em ~60 segundos. Use um timer no cliente, mostre a contagem regressiva e permita gerar um novo código.
- Sucesso chega pelo mesmo
/events?events=connection.update— não ha stream dedicado para pairing. Mantenha a subscricao deconnection.updateativa e feche a UI quando vierstatus: CONNECTED.
// 1. Garante que a sessao esta CONNECTING
await fetch(`${api}/instances/${id}/connect`, { method: 'POST', headers: auth });
// 2. Gera o codigo (phone inclui DDI, ex: "554137984905")
const res = await fetch(`${api}/instances/${id}/pairing-code`, {
method: 'POST',
headers: { 'Content-Type': 'application/json', ...auth },
body: JSON.stringify({ phone }),
});
const { pairing_code } = await res.json(); // ex: "SG3M82AE"
setCode(formatPairingCode(pairing_code)); // "SG3M-82AE"
// 3. Timer de expiracao
setTimeout(() => {
setCode(null);
toast.info('Codigo expirado, gere um novo.');
}, 60_000);
// 4. Sucesso vem via connection.update
// (ja esta assinado pelo stream de /events da rede de seguranca)
Checklist — como NÃO fazer#
| Anti-padrão | Consequência | O certo |
|---|---|---|
Usar new EventSource(url) sem token na URL |
401 silencioso, stream nunca abre | fetch() + ReadableStream ou @microsoft/fetch-event-source |
Token via query string (?token=) |
Rejeitado (401); query auth foi removida | Header Authorization: Bearer <token> |
Polling de GET /qr a cada 1s |
Spam de 60 req/min, QR desatualizado | SSE /qr/stream (push-based, atualiza sozinho) |
Não chamar POST /connect antes |
GET /qr devolve 400, stream so envia connected e fica parado |
Sempre POST /connect primeiro |
Não chamar GET /qr como snapshot |
Tela branca por 2-5s na primeira abertura | Snapshot sincrono antes do stream |
| Abrir stream, não cancelar no unmount | Vaza subscribers, esgota o limite de 20 e vira 429 | AbortController.abort() ao fechar |
| Abrir 2+ streams para a mesma instância | Consome slots a toa | Reaproveite um único stream via listener pub/sub |
Apagar o QR ao receber timeout |
Flicker visual, UX quebrada | Manter o QR visível até o próximo code |
| Não renovar o access token antes de reabrir | 401 durante reconexao longa | POST /auth/refresh antes de tentar reconectar |
Depender apenas do success do /qr/stream |
Perde o sucesso se o proxy buffer engolir o evento | Dupla subscricao com /events?events=connection.update |
| Reconectar sem backoff | Loop de erros em caso de falha persistente | Backoff exponencial (2s → 4s → 8s…), cap em 30s |
Ignorar o evento instance.banned |
Retry infinito em instância banida | Parar reconexao ao receber banned — veja seção 16 |
Limites operacionais#
| Limite | Valor | Observação |
|---|---|---|
| QRs por sessão de pareamento | 6 | ~20s cada, ~2min total antes de timeout |
| Validade do pairing code | ~60s | Gere novo após expirar |
| Subscribers por instância (SSE+WS somados) | 20 | Reutilize conexões, sempre cancele no unmount |
| Buffer de replay por instância | 100 eventos | Use Last-Event-ID ou ?last_event_id= para retomar após queda curta |
| Heartbeat do SSE | ~15s | Comentário : heartbeat — ignore no parser |
| Idle timeout recomendado do cliente | 45s | Se nada chegar nesse tempo, reconecte |
| Retry silencioso recomendado | até 10 vezes | Depois, mostrar prompt manual |
Referência rápida dos endpoints#
| Passo | Endpoint | Método | Finalidade |
|---|---|---|---|
| 1. Iniciar | /v1/instances/{id}/connect |
POST |
Dispara sessão whatsmeow e geração de QR |
| 2. Snapshot | /v1/instances/{id}/qr |
GET |
Último QR pendente (tela imediata) |
| 3. Stream | /v1/instances/{id}/qr/stream |
GET (SSE) |
Novos QRs + success/timeout |
| 4. Rede de seguranca | /v1/instances/{id}/events?events=connection.update |
GET (SSE) |
Status CONNECTED autoritativo |
| 5a. Retry | /v1/instances/{id}/restart |
POST |
Reabrir sessão após timeout/erro |
| 5b. Pairing | /v1/instances/{id}/pairing-code |
POST |
Alternativa ao QR (exige passo 1) |
Use está receita como ponto de partida e adapte ao seu stack. A implementação completa de referência está em frontend/src/views/instances/components/ConnectionModal.vue no próprio repositorio do Catcher Console.