Instâncias WhatsApp

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:

json
{
  "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:

json
{
  "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:

json
[
  {
    "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_error aparece so quando a instância teve problema (limpo ao conectar); ban_expiry/ban_reason so após ban temporario; disconnected_at/offline_duration_seconds/offline_duration_human/offline_alert_level so quando offline; last_logged_out_401_at so após restrição 401; proxy so quando ha IP dedicado vinculado. supports_device_info indica se GET /v1/instances/{instanceId}/device e suportado para a instância. false em instâncias wwebjs; clientes devem checar esta capability antes de chamar o endpoint. tier e calculado em tempo de resposta: healthy, stale, degraded, offline, critical_offline, intentional, pending, banned. GET /v1/instances NÃO retorna uptime — esse campo aparece apenas em GET /v1/instances/{instanceId}.


GET/v1/instances/{instanceId}#

Retorna detalhes de uma instância.

Auth: Owner, Admin

Resposta 200:

json
{
  "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_url aparece apenas quando ha avatar em cache. uptime aparece apenas quando status=CONNECTED. Diferente da listagem, este objeto NÃO retorna last_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:

json
{
  "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 - name fora do tamanho permitido (3-80)
  • 404 INSTANCE_NOT_FOUND - instância não pertence a empresa autenticada
  • 409 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 200 com 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:

json
{
  "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:

json
{
  "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 aceito
  • 400 BAD_REQUEST - max_outbound_without_inbound fora do range 1-10, business_hours_start fora de 0-23, business_hours_end fora de 1-24, link_spam_threshold fora de 1-10000, auto_reject_message com mais de 500 caracteres, ou temperature_curve com valor fora de 1-50 / não-decrescente
  • 404 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; enforce aplica a trava nas instâncias com account_pressure_enforced=true (PATCH .../settings); as demais continuam em observação. off desliga. 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.

json
{ "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:

json
{
  "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 autenticada
  • 503 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).

json
{ "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).

json
{ "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:

  1. 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.Message com IsFromMe=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.
  2. 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 em temperature_curve (default cold 3 · warm 5 · engaged 7 · hot 10 · very_hot 15, personalizável por instância em PATCH /settings). Bloqueio retorna 409 CONFLICT com error_code: "BLOCKED_TEMPERATURE_LIMIT" (payload inclui remote_jid, score, tier, max_consecutive, outbound_consecutive).
    • fixed → vale o limite fixo max_outbound_without_inbound (1-10, default 2), rolling window 7d. Bloqueio retorna 409 CONFLICT com error_code: "BLOCKED_NO_RECIPROCITY" (payload inclui remote_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):

json
{
  "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 via POST /v1/instances/{instanceId}/official/credentials (abaixo) — a validação contra a Graph API já transiciona a conexão para CONNECTED. O connect nesse 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:

json
{
  "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:

json
{
  "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:

json
{ "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:

json
{ "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:

json
{
  "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:

json
{
  "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:

json
{
  "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:

json
{
  "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
json
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):

json
// 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 (o interactive referencia flow_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é
json
{ "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)
json
{ "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_id que 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)
json
{ "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. O ctwa_clid é o MESMO que já chega no ad_context do message.received — junte os dois e você fecha o loop anúncio → conversa → resultado, que é o buraco negro de quem roda CTWA. Requer que o field automatic_events esteja 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:

json
{ "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:

json
{
  "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:

json
{ "provider": "wwebjs", "force": false }

Resposta 200:

json
{ "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):

json
{
  "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:

json
{
  "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, o history.sync automá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, omitir since e window_seconds usa 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 e source="external" para outbound vindo do celular/WhatsApp Web. Por padrão elas também disparam message.received/message.sent, entram no histórico de eventos/webhooks e carregam historical=true + history_source="history_import" para o consumidor distinguir replay/backfill de tráfego ao vivo.

historical responde "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.sent sem historical — 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 marcado historical=true. A importação EXPLÍCITA de histórico (POST /history/import, que pede dias) continua sempre historical=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 por history.sync; no wwebjs, a resposta 200 já traz os contadores do replay. Leia as mensagens importadas pelos endpoints de chat/mensagens.

Erros:

  • 400 - JSON inválido
  • 404 - Instância não encontrada
  • 400 - 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:

json
{
  "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 - instanceId ausente
  • 404/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:

json
{
  "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 - instanceId ausente
  • 500 - 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:

json
{
  "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 - instanceId ausente
  • 500 - 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:

json
{
  "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 - instanceId ausente
  • 500 - 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:

json
{
  "instance_id": "84c2e480-...",
  "company_id": 7,
  "total": 1240,
  "showing": 200,
  "limit": 200,
  "lines": ["{\"level\":\"info\",...}"]
}

Erros:

  • 400 - instanceId ausente
  • 404 - arquivo de log não encontrado
  • 503 - 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:

json
{
  "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 - instanceId ausente
  • 403 FORBIDDEN - contexto tenant ausente
  • 404 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:

json
{
  "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 - instanceId ausente
  • 404 INSTANCE_NOT_FOUND - instância não encontrada
  • 503 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:

json
{
  "qr": "2@abc123...",
  "qr_base64": "iVBORw0KGgo...",
  "mime_type": "image/png"
}

qr contem a string raw para gerar localmente; qr_base64 contem a imagem PNG do QR em base64. Se a instância não tiver QR pendente, retorna 400.

Contrato do QR (idêntico em todos os providers). qr_base64 é sempre base64 PURO — NUNCA inclui o prefixo data:image/png;base64,. Para exibir, o consumidor adiciona o prefixo: <img src="data:image/png;base64,${qr_base64}">. qr e qr_base64 são atômicos: ou ambos vêm preenchidos juntos, ou ambos vazios — nunca um qr raw sem a imagem correspondente. mime_type é sempre image/png quando há QR. Esse contrato vale igualmente para GET /qr, o stream GET /qr/stream e 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:

json
{
  "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:

json
{
  "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 skipped ou 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

text
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

timeout vs stopped: timeout é a expiração de UM QR (a sessão pode emitir o próximo code); stopped é o FIM da tentativa — o servidor parou de forçar QRs e só um novo POST /connect recomeça. Trate stopped como terminal: pare de esperar code e ofereça o botão de gerar novo QR. O número de QRs por tentativa no provider wwebjs é configurável no servidor via WWEBJS_QR_MAX_REGENS (padrão 5).

Nota: O campo qr_base64 contem a imagem PNG do QR pronta para exibir: <img src="data:image/png;base64,${qr_base64}">. O campo qr contem a string raw para gerar o QR localmente.

Proxy reverso: Se usar Apache/Nginx como proxy, desabilite compressao e buffering para endpoints SSE (/qr/stream e /events). Sem isso, o browser recebe ERR_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/stream do superadmin segue a mesma regra). O servidor envia um comentário SSE : ping a 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 sem success/stopped, reabra-o (sem novo POST /connect) — o success é publicado uma única vez, no momento do pareamento. Para confirmar sem depender do stream, consulte GET /v1/instances/{id} (status: CONNECTED) ou o evento connection.update com status: 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.update com status: disconnected e reason: connect_failed_no_qr (o stream de QR fica em silêncio). Um novo POST /connect recomeç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:

json
{
  "phone": "554137984905"
}

Resposta 200:

json
{
  "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#

text
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)#

text
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 recebe 429 Too Many Requests. Sempre use AbortController para 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.

javascript
/**
 * 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 /qr antes 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 API fetchEventSource() identica ao EventSource nativo mas com suporte a headers, retry automático e AbortController.

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:

bash
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:

go
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.).

javascript
// 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.

javascript
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:

  1. Requer POST /connect ANTES. A chamada POST /pairing-code so funciona se a instância estiver em CONNECTING ou QR_PENDING — caso contrario retorna 400 instance not connected, call connect first. Na prática, execute o mesmo fluxo do QR e apenas troque a interface.
  2. Código expira em ~60 segundos. Use um timer no cliente, mostre a contagem regressiva e permita gerar um novo código.
  3. Sucesso chega pelo mesmo /events?events=connection.update — não ha stream dedicado para pairing. Mantenha a subscricao de connection.update ativa e feche a UI quando vier status: CONNECTED.
javascript
// 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.