instance.status

EVENTOinstance.statusdesde M3envelope v1

Estado da instância mudou.

Quando é emitido

Emitido em toda transição de estado da instância (starting, qr_pending, connecting, connected, reconnecting, logged_out, banned, failed, stopped). reason explica alguns estados, como proxy_unreachable em reconnecting ou temp_banned:<duração> em failed.

Campos de data

Campo	Tipo	Descrição
state	string	Novo estado. Veja Instâncias e estados.
reason	string	Motivo, quando houver (opcional).

O envelope (id, type, version, instance_id, timestamp,data) está em Visão geral. Campos novos podem ser adicionados emdata sem mudar a versão: ignore os que não conhecer.

Exemplos

Conectou

{
  "id": "evt_0a7d3c9e1f5b2486",
  "type": "instance.status",
  "version": 1,
  "instance_id": "inst_7f3a9c2e5b1d4086",
  "timestamp": "2026-10-17T13:40:02.511Z",
  "data": {
    "state": "connected"
  }
}

Proxy fora do ar

{
  "id": "evt_6b2e8d0a4c1f7395",
  "type": "instance.status",
  "version": 1,
  "instance_id": "inst_7f3a9c2e5b1d4086",
  "timestamp": "2026-10-17T15:12:44.020Z",
  "data": {
    "state": "reconnecting",
    "reason": "proxy_unreachable"
  }
}

Entrega e ordem

• Por webhook: pelo menos uma vez, com retry por até 24 horas. O mesmo evento pode chegar duas vezes: deduplique porX-LiteZap-Event-Id. Veja Entrega e retentativas.
• A ordem entre eventos não é garantida (retentativas reordenam): use timestamp.
• Por SSE: ao vivo, sem replay. Veja Tempo real com SSE.
• Para assinar só este tipo: "events": ["instance.status"] no webhook, ou?types=instance.status no SSE.

Relacionados: instance.qr · instance.pair_code

Equivalente na Z-API: Ao conectar / Ao desconectar.