Webhooks connected e disconnected - Wabox

connected

{
  "type": "connected",
  "event_id": "01J5Q8ZK3M4N5P6Q7R8S9T0V1W",
  "instance_id": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b",
  "momment": 1786968030000,
  "connected": true,
  "phone": "5511999998888"
}

Dispara quando o número lê o QR code / código de pareamento e quando a sessão reconecta depois de uma queda. phone é o número conectado — use para confirmar que a instância está ligada ao número certo. Ao conectar, a fila começa a drenar o que acumulou enquanto a instância estava fora.

disconnected

{
  "type": "disconnected",
  "event_id": "01J5Q8ZK3M4N5P6Q7R8S9T0V1X",
  "instance_id": "8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b",
  "momment": 1786971600000,
  "disconnected": true,
  "reason": "logged_out",
  "error": "Device has been disconnected"
}

`reason`	O que aconteceu	Precisa de ação?
`network`	Rede caiu entre o Wabox e o WhatsApp, ou o celular ficou muito tempo offline	Não — reconecta sozinho; `connected` avisa quando voltar
`stream_replaced`	Outra sessão do WhatsApp Web com o mesmo aparelho vinculado assumiu	Não — reconecta sozinho. Se repete, alguém está usando as credenciais da sessão em outro lugar
`logged_out`	O aparelho foi removido em Aparelhos conectados no celular, ou a sessão expirou	Sim: ler o QR de novo (`GET /qr-code`)
`banned`	O WhatsApp baniu o número	Sim: o número não volta; leia Boas práticas
`stopped`	A instância foi parada pela API/painel ou por assinatura vencida	Depende: `POST /restart` ou regularizar a assinatura
`engine_shutdown`	Manutenção do lado do Wabox	Não — reconecta ao voltar
`unknown`	Queda sem motivo identificado	Aguarde; se não voltar, `POST /restart`

error é a mensagem crua do protocolo, útil para suporte.

Recomendações

Trate logged_out e banned como alertas: avise quem opera o número (e-mail, Slack). Enquanto isso, os envios continuam entrando na fila, a menos que disable_enqueue_when_disconnected esteja ligado.
Não reaja a network/stream_replaced com POST /restart automático: a reconexão já está em curso e reiniciar só atrasa.
GET /status continua sendo a fonte de verdade para consultas pontuais; os webhooks evitam ficar consultando em loop.