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.

`session.created`

Disparado quando uma conexão da API Oficial termina de ser provisionada pelo connect hospedado — o fluxo do SDK connect.start(), usado por quem revende a API Oficial para os próprios clientes. Vai para o webhookUrl daquela conexão, sempre, em paralelo ao resultado que o connect.start() devolve no navegador. É o único aviso que chega no mobile: lá o popup abre como aba e o postMessage de volta para a sua página não acontece, então o start() pode rejeitar mesmo com a conexão criada. Use connect.start({ metadata }) para carregar o seu identificador de cliente e reencontrá-lo aqui em data.metadata.

{
  "event": "session.created",
  "sessionId": "cloud-9f2c1e5a-…",
  "timestamp": "2026-08-02T12:00:00.000Z",
  "data": {
    "connectionId": "9f2c1e5a-…",
    "connectionType": "cloud_api",
    "status": "connected",
    "wabaId": "123456789",
    "phoneNumberId": "987654321",
    "businessId": "555555555",
    "phoneNumber": "+5511999999999",
    "verifiedName": "Acme Ltda",
    "accessToken": "EAAG…",
    "accessTokenKind": "long_lived",
    "accessTokenExpiresAt": "2026-10-01T00:00:00.000Z",
    "webhookMode": "normalized",
    "metadata": { "tenantId": "acme-42" }
  }
}

string

required

Id da conexão — é o sessionId nas rotas de envio.

string

required

WhatsApp Business Account do cliente na Meta.

string

required

Id do número na Cloud API.

string

required

Access token da Meta daquela conexão, já descriptografado. É segredo: pode enviar mensagens e administrar a WABA.

string

required

permanent, long_lived, short_lived ou unknown.

string

Expiração em ISO-8601, ou null quando o token não expira.

object

required

O JSON livre que você passou em connect.start({ metadata }). {} quando não foi enviado.

Como o payload carrega o access token, o evento só é entregue no webhookUrl da própria conexão e apenas por HTTPS — um endpoint http:// é recusado, e o disparo fica registrado no log. Nos logs de webhook o token aparece como [REDACTED]; ele existe só no corpo entregue ao seu endpoint.

`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.

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"
  }
}

string

required

Código de pareamento a ser digitado no aparelho.

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
  }
}

string

required

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

string

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

string

Número de telefone da conta conectada.

string

Nome exibido da conta conectada.

string

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

boolean

true quando a sessão acabou de conectar.

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

API Oficial (SaaS)

Assistente de Integração

Ligações

Webhooks

Eventos de conexão

`session.created`

`connection.qrcode`

`connection.paircode`

`connection.status`

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

​session.created

​connection.qrcode

​connection.paircode

​connection.status

​logged_out (despachado como connection.status)

`session.created`

`connection.qrcode`

`connection.paircode`

`connection.status`

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