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

# Sessions

> Create a WhatsApp Alternative session, scan the QR code, and link it to a sender.

A **session** is one linked-device connection to WhatsApp. You create it, poll it for a QR code, scan the QR from the phone, and then link it to a sender so that sender's `whatsapp_alt` traffic flows through the number.

<Note>
  The `/v1/whatsapp-alt/*` endpoints require the WhatsApp Alternative feature to be enabled for your team and are not available with test-mode API keys.
</Note>

## Session lifecycle

| Status           | Meaning                                                            |
| ---------------- | ------------------------------------------------------------------ |
| `initializing`   | Session created, the connection is starting.                       |
| `qr_ready`       | `qrCode` is available — scan it from the phone to link.            |
| `authenticating` | QR scanned, handshaking.                                           |
| `ready`          | Linked and connected. You can send and receive.                    |
| `disconnected`   | Unlinked or dropped (Zavu reconnects automatically when possible). |
| `failed`         | Could not connect (see `lastError`).                               |

## 1. Create a session

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.zavu.dev/v1/whatsapp-alt/sessions \
    -H "Authorization: Bearer $ZAVU_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{ "displayName": "Support line" }'
  ```

  ```typescript TypeScript theme={null}
  const { session } = await zavu.whatsappAlt.sessions.create({
    displayName: "Support line",
  });
  ```

  ```python Python theme={null}
  resp = zavu.whatsapp_alt.sessions.create(display_name="Support line")
  session = resp.session
  ```
</CodeGroup>

The session starts in `initializing`. The QR is generated asynchronously — poll the session until `qrCode` appears.

By default the session egresses through the **managed Zavu residential proxy**, geo-matched to the number's country. To route it through your own Android device instead, pass an `egress` object — see [Egress & Fallback](/guides/whatsapp-alt/egress).

## 2. Poll for the QR code

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.zavu.dev/v1/whatsapp-alt/sessions/SESSION_ID \
    -H "Authorization: Bearer $ZAVU_API_KEY"
  ```

  ```typescript TypeScript theme={null}
  const { session } = await zavu.whatsappAlt.sessions.retrieve("SESSION_ID");
  if (session.status === "qr_ready" && session.qrCode) {
    // Render session.qrCode as a QR image for the user to scan.
  }
  ```

  ```python Python theme={null}
  resp = zavu.whatsapp_alt.sessions.retrieve("SESSION_ID")
  session = resp.session
  if session.status == "qr_ready" and session.qr_code:
      ...  # render the QR
  ```
</CodeGroup>

Poll every 2–3 seconds until `status` is `qr_ready`. The `qrCode` field is the QR payload — render it as a QR image. It rotates until scanned, so keep polling and re-render when it changes.

## 3. Scan from the phone

On the phone, open **WhatsApp → Linked devices → Link a device**, then scan the QR. The session moves through `authenticating` to `ready`, and `phoneNumber` and `pushName` are populated.

<Tip>
  A number can be linked to several devices at once, so linking to Zavu doesn't log the number out of the phone. Do not scan the same session's QR from two places.
</Tip>

## 4. Link the session to a sender

Attach the ready session to a sender so its outbound `whatsapp_alt` messages route through this number and inbound messages are attributed to it.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.zavu.dev/v1/whatsapp-alt/sessions/SESSION_ID/link \
    -H "Authorization: Bearer $ZAVU_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{ "senderId": "sender_12345" }'
  ```

  ```typescript TypeScript theme={null}
  await zavu.whatsappAlt.sessions.link("SESSION_ID", {
    senderId: "sender_12345",
  });
  ```

  ```python Python theme={null}
  zavu.whatsapp_alt.sessions.link("SESSION_ID", sender_id="sender_12345")
  ```
</CodeGroup>

You can later detach with `POST /v1/whatsapp-alt/sessions/{sessionId}/unlink`.

## Managing a session

| Action    | Endpoint                                        | Notes                                                                                                                                         |
| --------- | ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| List      | `GET /v1/whatsapp-alt/sessions`                 | Paginated.                                                                                                                                    |
| Get       | `GET /v1/whatsapp-alt/sessions/{id}`            | Live `status` + `qrCode` while linking.                                                                                                       |
| Reconnect | `POST /v1/whatsapp-alt/sessions/{id}/reconnect` | Re-initialize after `failed`/`disconnected`; reconnects without a new QR if credentials are still valid.                                      |
| Log out   | `POST /v1/whatsapp-alt/sessions/{id}/logout`    | Clears credentials; the device disappears from the phone's Linked devices. The session row is kept — reconnect to link again with a fresh QR. |
| Delete    | `DELETE /v1/whatsapp-alt/sessions/{id}`         | Deletes the session, unlinks its senders, and logs the device out.                                                                            |

<Warning>
  Reconnect and logout behave differently: **reconnect** keeps the link alive (no QR), while **logout** unlinks the device and requires scanning a new QR to reconnect.
</Warning>

## Next steps

<CardGroup cols={2}>
  <Card title="Egress & Fallback" icon="route" href="/guides/whatsapp-alt/egress">
    Choose how the number reaches WhatsApp and keep it 100% active.
  </Card>

  <Card title="Sending & Receiving" icon="messages" href="/guides/whatsapp-alt/sending-receiving">
    Send on the `whatsapp_alt` channel and handle inbound webhooks.
  </Card>
</CardGroup>