Skip to main content
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.
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.

​
Session lifecycle

StatusMeaning
initializingSession created, the connection is starting.
qr_readyqrCode is available — scan it from the phone to link.
authenticatingQR scanned, handshaking.
readyLinked and connected. You can send and receive.
disconnectedUnlinked or dropped (Zavu reconnects automatically when possible).
failedCould not connect (see lastError).

​
1. Create a session

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

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

resp = zavu.whatsapp_alt.sessions.create(display_name="Support line")
session = resp.session
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.

​
2. Poll for the QR code

curl https://api.zavu.dev/v1/whatsapp-alt/sessions/SESSION_ID \
  -H "Authorization: Bearer $ZAVU_API_KEY"

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

resp = zavu.whatsapp_alt.sessions.retrieve("SESSION_ID")
session = resp.session
if session.status == "qr_ready" and session.qr_code:
    ...  # render the QR
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.
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.
Attach the ready session to a sender so its outbound whatsapp_alt messages route through this number and inbound messages are attributed to it. 
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" }'

await zavu.whatsappAlt.sessions.link("SESSION_ID", {
  senderId: "sender_12345",
});

zavu.whatsapp_alt.sessions.link("SESSION_ID", sender_id="sender_12345")
You can later detach with POST /v1/whatsapp-alt/sessions/{sessionId}/unlink.

​
Managing a session

ActionEndpointNotes
ListGET /v1/whatsapp-alt/sessionsPaginated.
GetGET /v1/whatsapp-alt/sessions/{id}Live status + qrCode while linking.
ReconnectPOST /v1/whatsapp-alt/sessions/{id}/reconnectRe-initialize after failed/disconnected; reconnects without a new QR if credentials are still valid.
Log outPOST /v1/whatsapp-alt/sessions/{id}/logoutClears credentials; the device disappears from the phone’s Linked devices. The session row is kept — reconnect to link again with a fresh QR.
DeleteDELETE /v1/whatsapp-alt/sessions/{id}Deletes the session, unlinks its senders, and logs the device out.
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.

​
Next steps

Egress & Fallback

Choose how the number reaches WhatsApp and keep it 100% active.

Sending & Receiving

Send on the whatsapp_alt channel and handle inbound webhooks.