> ## Documentation Index
> Fetch the complete documentation index at: https://docs.d-api.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Connection events

> QR code, pairing code, and session status changes.

These events track the **connection lifecycle** of a WhatsApp session: QR code
generation, the pairing code, and status changes (connected, disconnected,
logged out). All of them follow the
[common envelope](https://docs.d-api.cloud/en/whatsapp/webhooks/visao-geral.md) — the event-specific content
lives in `data`.

## `session.created`

Fires when an **Official API** connection finishes being provisioned through the
[hosted connect](https://docs.d-api.cloud/en/api-oficial/saas.md) — the SDK `connect.start()` flow,
used by those who resell the Official API to their own customers.
It is sent to that connection's `webhookUrl` **every time**, in parallel with the
result that `connect.start()` returns in the browser.

It is the only notification that arrives on **mobile**: there the popup opens as a
tab and the `postMessage` back to your page does not happen, so `start()` may
reject even though the connection was created. Use `connect.start({ metadata })` to
carry your own customer identifier and find it again here in `data.metadata`.

```json theme={null}
{
  "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" }
  }
}
```

**connectionId** `string` *required*

Connection ID — this is the `sessionId` in the sending routes.

**wabaId** `string` *required*

The customer's WhatsApp Business Account at Meta.

**phoneNumberId** `string` *required*

ID of the phone number in the Cloud API.

**accessToken** `string` *required*

Meta access token for that connection, already decrypted. **It is a secret**: it
can send messages and manage the WABA.

**accessTokenKind** `string` *required*

`permanent`, `long_lived`, `short_lived`, or `unknown`.

**accessTokenExpiresAt** `string`

Expiration in ISO-8601, or `null` when the token does not expire.

**metadata** `object` *required*

The free-form JSON you passed in `connect.start({ metadata })`. `{}` when it was
not sent.

> [!WARNING]
>
> Because the payload carries the access token, the event is only delivered to the
> `webhookUrl` **of the connection itself** and only over **HTTPS** — an `http://`
> endpoint is rejected, and the attempt is recorded in the log. In the
> [webhook logs](https://docs.d-api.cloud/en/api-reference/webhooks/listar-logs) the token shows up as
> `[REDACTED]`; it only exists in the body delivered to your endpoint.

## `connection.qrcode`

Fires when a **new QR code** is generated to authenticate the session. It includes
the QR text and the image already rendered in base64 (PNG), ready to display.

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

**qr** `string` *required*

Text content of the QR code to be scanned by WhatsApp.

**qrImage** `string`

QR code image as a data URL (base64 PNG). May be `null` if image generation
fails — in that case, use the `qr` field to render it.

> [!NOTE]
>
> QR codes identical to the last one generated for the session are
> **deduplicated** and do not trigger a new webhook.

## `connection.paircode`

Fires when a **pairing code** is generated (connecting by phone number, without
scanning a QR).

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

**code** `string` *required*

Pairing code to be entered on the device.

**phone** `string` *required*

Phone number the code was generated for.

## `connection.status`

Fires on every **status change** of the connection. The `data.status` field
identifies the state. The other fields vary depending on the state.

```json theme={null}
{
  "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*

Connection state. Possible values: `connected`, `disconnected`,
`logged_out`, and `qrcode_timeout`.

**jid** `string`

JID of the connected account. Present when the status is `connected`.

**phone** `string`

Phone number of the connected account.

**name** `string`

Display name of the connected account.

**profilePictureUrl** `string`

URL of the account's profile picture, when available.

**connected** `boolean`

`true` when the session has just connected.

**reason** `string`

Disconnection reason. Present in the `disconnected` and `logged_out` statuses.

### `logged_out` (dispatched as `connection.status`)

When the session is **logged out** (e.g. the device was removed by the user),
the event is delivered as `connection.status` with `data.status: "logged_out"`.

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

> [!NOTE]
>
> There is no separate `logged_out` webhook event: logout is always
> delivered as `connection.status` with `data.status: "logged_out"`. To
> detect that the session needs to be reconnected, check
> `data.status === "logged_out"` (and also `"disconnected"`).

### `qrcode_timeout` (dispatched as `connection.status`)

When a session spends **45 minutes generating QR codes** without anyone scanning
them, and without any QR request during that period, D-API **hibernates** the
session: the process that generates the QR codes is shut down, the
`connection.qrcode` events stop arriving, and you receive a single
`connection.status` with `data.status: "qrcode_timeout"`.

```json theme={null}
{
  "event": "connection.status",
  "sessionId": "my-session",
  "timestamp": "2026-10-28T18:45:00.000Z",
  "data": {
    "status": "qrcode_timeout",
    "timestamp": "2026-10-28T18:45:00.000Z"
  }
}
```

From then on, the session shows up as `disconnected` in
`GET /api/v1/sessions/{sessionId}`, with `disconnectReason: "qrcode_timeout"`. Nothing is deleted: the session, its
settings, and the webhook stay the same.

To start generating QR codes again, just request a QR as you already do:

* [`GET /api/v1/sessions/{sessionId}/qr`](https://docs.d-api.cloud/en/api-reference/endpoints/conectar-qr);
* `POST /api/v1/sessions/{sessionId}/connect` or `POST /api/v1/sessions/{sessionId}/restart`;
* `GET /api/v1/sessions/{sessionId}/pair-code`;
* open the session's public QR link.

The first request wakes the session up and responds as before, with the previous QR
marked as expired (`expired: true`). The new QR arrives within a few seconds,
through the QR route itself (query it again) or through the `connection.qrcode` event.
Each QR request also resets the 45-minute countdown, so a screen that
polls the QR while the user has it open is never hibernated.

> [!NOTE]
>
> `qrcode_timeout` is not an error and requires no action if nobody is trying
> to connect that number. If you show the QR to your user only from the
> `connection.qrcode` webhook, handle `qrcode_timeout` by calling
> `GET /api/v1/sessions/{sessionId}/qr` when they return to the connection screen.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.