Conexão da instância

Evento: connection · Transporte: POST para o seu receptor

Acompanhe mudanças do ciclo de conexão da instância. Use instance.status para atualizar a interface e decidir quando consultar /instance/status.

Quando é enviado

Conexão estabelecida e transições de desconexão notificadas pelo ciclo da sessão. Uma queda transitória de socket pode ser suprimida durante recuperação; não conte com um webhook para cada tentativa interna de reconexão.

Como interpretar

event_id identifica a notificação produzida pelo fluxo de conexão.
instance.status descreve o estado informado; lastDisconnectReason ajuda no diagnóstico.
type, quando presente, pode indicar a origem da transição, como Disconnected ou TemporaryBan.
Campos como temporaryBan só aparecem quando aplicáveis. Consulte o estado atual se eventos chegarem atrasados.

Habilitar este evento

Adicione connection à lista events do webhook da instância. Preserve os outros eventos de que sua integração precisa.

{
  "enabled": true,
  "url": "https://seu-sistema.example/hooks/whatsapp",
  "events": [
    "connection"
  ]
}

Envie essa configuração para POST /webhook, usando o header token. O JSON acima configura a assinatura; os exemplos de entrega abaixo são o que seu servidor recebe.

Campos do payload

O envelope comum vem na raiz. Campos condicionais podem estar ausentes ou nulos conforme o evento; não use a tabela como obrigação de presença de todos os campos.

Campo	Tipo	Significado
`EventType`	string	Obrigatório. Tipo de evento, por exemplo connection ou messages.
`owner`	string	Obrigatório. Consulte o objeto ou exemplo correspondente.
`token`	string	Obrigatório. Token da instância; dado sensível.
`BaseUrl`	string	Obrigatório. Consulte o objeto ou exemplo correspondente.
`instanceName`	string	Consulte o objeto ou exemplo correspondente.
`event_id`	string	Identificador da notificação de conexão; não é um campo universal dos outros eventos.
`instance`	object	Estado da instância.
`instance.name`	string	Nome da instância.
`instance.status`	string	Estado da conexão informado pelo evento.
`instance.lastDisconnectReason`	string	Motivo disponível da desconexão; pode ser unknown.
`instance.lastDisconnect`	string	Data textual da última desconexão.
`type`	string	Origem/tipo da transição, quando disponível.

Exemplos de entrega

Exemplos ilustrativos com identificadores fictícios. O conteúdo específico e os campos opcionais variam.

Conexão estabelecida

{
  "EventType": "connection",
  "owner": "5511999999999",
  "token": "INSTANCE_TOKEN",
  "BaseUrl": "https://seu-servidor.example",
  "instanceName": "Atendimento",
  "event_id": "f51310de-8e2b-4ef5-8065-dcd67e764c65",
  "instance": {
    "name": "Atendimento",
    "status": "connected"
  }
}

Desconexão notificada

{
  "EventType": "connection",
  "owner": "5511999999999",
  "token": "INSTANCE_TOKEN",
  "BaseUrl": "https://seu-servidor.example",
  "instanceName": "Atendimento",
  "event_id": "4d42a099-7921-43ec-9774-da72901bbf13",
  "type": "Disconnected",
  "instance": {
    "name": "Atendimento",
    "status": "disconnected",
    "lastDisconnectReason": "unknown",
    "lastDisconnect": "2026-09-08 12:00:00.000Z"
  }
}

Responder ao webhook

Seu receptor deve aceitar o POST JSON e devolver uma resposta 2xx rapidamente, após validar e registrar o recebimento. O corpo da resposta não é um comando para a API. Processe trabalho demorado separadamente.

O worker não repete automaticamente uma entrega HTTP malsucedida. Consulte diagnóstico de webhooks e implemente a reconciliação necessária. Eventos repetidos ou fora de ordem ainda precisam ser tolerados pelo receptor.