Skip to main content
Dispara uma vez a cada mudança de status da instância, o mesmo valor que GET /status devolve. É o único webhook de conexão. Com ele você mostra a tela de QR code na hora certa, libera o canal quando o número entra e avisa quando ele cai, sem consultar a API em loop.

Status

Motivo da desconexão

O QR code não vem no webhook

O código muda a cada poucos segundos, então o Wabox nunca o envia. status: "qr" é o sinal para o seu sistema começar a buscar GET /qr-code (e renovar enquanto o status for qr). Você recebe um instance_status quando a instância passa a aguardar o QR, não um por código gerado. Quando o cliente lê o código, chegam connecting e depois connected. O Wabox gera QR codes por cerca de 13 minutos. Se ninguém ler nesse tempo, o pareamento para. Chega disconnected com disconnect_reason: qr_timeout e nenhum QR novo é gerado. Para tentar de novo, chame GET /qr-code (ou GET /qr-code/image, ou o código de telefone). O pareamento recomeça do zero, com mais ~13 minutos.

Configuração

Configure com instance_status_url em PUT /webhooks (ou PUT /webhooks/instance_status com { "value": "https://..." }), com PUT /account/webhooks para o workspace inteiro, ou no campo Ao mudar o status da instância do painel. No modo de URL única ele já chega em single_url. Para silenciar sem apagar a URL, use ignore_instance_status_callback: true.

Recomendações

  • Trate logged_out e banned como alertas e 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 disconnected com um POST /restart automático, porque a reconexão já está em curso e reiniciar só atrasa. Com qr_timeout também não. Gere o QR de novo só quando alguém for ler.
  • Eventos podem chegar fora de ordem numa retentativa. Use momment para não deixar um disconnected antigo derrubar um canal que já voltou.
  • GET /status continua sendo a fonte de verdade para consultas pontuais; o webhook evita ficar consultando em loop.
instance_status substituiu os antigos webhooks connected e disconnected (e os campos connected_url / disconnected_url). O que eles traziam está aqui: phone ao conectar, disconnect_reason + reason ao cair. O Wabox migrou automaticamente para instance_status_url quem tinha uma dessas URLs configurada.