Eventos de conexão

Estes eventos acompanham o ciclo de conexão de uma sessão do WhatsApp: a geração do QR code, o código de pareamento, e as mudanças de status (conectado, desconectado, deslogado). Todos seguem o envelope comum — o conteúdo específico fica em data.

`connection.qrcode`

Disparado quando um novo QR code é gerado para autenticar a sessão. Inclui o texto do QR e a imagem já renderizada em base64 (PNG), pronta para exibir.

{
  "event": "connection.qrcode",
  "sessionId": "my-session",
  "timestamp": "2026-01-24T22:00:00.000Z",
  "data": {
    "qr": "2@abc...",
    "qrImage": "data:image/png;base64,iVBOR..."
  }
}

string

required

Conteúdo textual do QR code a ser escaneado pelo WhatsApp.

qrImage

string

Imagem do QR code como data URL (PNG em base64). Pode vir null caso a geração da imagem falhe — nesse caso use o campo qr para renderizar.

QR codes idênticos ao último gerado para a sessão são deduplicados e não geram novo webhook.

`connection.paircode`

Disparado quando um código de pareamento é gerado (conexão por número de telefone, sem escanear QR).

{
  "event": "connection.paircode",
  "sessionId": "my-session",
  "timestamp": "2026-01-24T22:00:05.000Z",
  "data": {
    "code": "ABCD-1234",
    "phone": "5511999999999"
  }
}

code

string

required

Código de pareamento a ser digitado no aparelho.

phone

string

required

Número de telefone para o qual o código foi gerado.

`connection.status`

Disparado a cada mudança de status da conexão. O campo data.status identifica o estado. Os demais campos variam conforme o estado.

{
  "event": "connection.status",
  "sessionId": "my-session",
  "timestamp": "2026-01-24T22:00:30.000Z",
  "data": {
    "status": "connected",
    "jid": "558005915338@s.whatsapp.net",
    "phone": "558005915338",
    "name": "Minha Empresa",
    "connected": true
  }
}

status

string

required

Estado da conexão. Valores possíveis: connected, disconnected e logged_out.

jid

string

JID da conta conectada. Presente quando o status é connected.

phone

string

Número de telefone da conta conectada.

name

string

Nome exibido da conta conectada.

profilePictureUrl

string

URL da foto de perfil da conta, quando disponível.

connected

boolean

true quando a sessão acabou de conectar.

reason

string

Motivo da desconexão. Presente nos status disconnected e logged_out.

`logged_out` (despachado como `connection.status`)

Quando a sessão é deslogada (ex: o aparelho foi removido pelo usuário), o evento é entregue como connection.status com data.status: "logged_out".

{
  "event": "connection.status",
  "sessionId": "my-session",
  "timestamp": "2026-01-24T22:10:00.000Z",
  "data": {
    "status": "logged_out",
    "reason": "device_removed"
  }
}

Não existe um evento logged_out separado no webhook: o logout é sempre entregue como connection.status com data.status: "logged_out". Para detectar que a sessão precisa ser reconectada, verifique data.status === "logged_out" (e também "disconnected").

Introdução

Assistente de Integração

Ligações

Webhooks

Eventos de conexão

`connection.qrcode`

`connection.paircode`

`connection.status`

`logged_out` (despachado como `connection.status`)

​connection.qrcode

​connection.paircode

​connection.status

​logged_out (despachado como connection.status)

`connection.qrcode`

`connection.paircode`

`connection.status`

`logged_out` (despachado como `connection.status`)