WhatsApp Sessions

A Session represents a connected WhatsApp phone number. You must create and pair a session before you can send or receive messages.

Create a Session

POST /v1/whatsapp/sessions

Creates a new WhatsApp session and returns a QR code for pairing. Scan the QR code with the WhatsApp app on the phone you want to connect.

Request Body

Parameter	Type	Required	Description
name	string	Yes	A human-readable label for this session (e.g., "Support Bot").
webhook_url	string	No	Override the default webhook URL for this session's events.

cURL

curl -X POST https://sendapi.co/v1/whatsapp/sessions \
  -H "Authorization: Bearer sk_live_123456789" \
  -H "Content-Type: application/json" \
  -d '{"name": "Support Bot"}'

Node.js

const session = await client.whatsapp.sessions.create({
  name: 'Support Bot'
});

console.log(session.qr_code); // base64 PNG to render

Python

session = client.whatsapp.sessions.create(name="Support Bot")
print(session.qr_code)

Response

{
  "id": "sess_01H8BKF...Z2T",
  "name": "Support Bot",
  "status": "pending",
  "qr_code": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
  "qr_expires_at": "2026-03-09T14:32:00Z",
  "created_at": "2026-03-09T14:30:00Z"
}

Render the qr_code as an image and scan it with WhatsApp on the device you want to connect. The QR code expires in 2 minutes. You can request a fresh one via GET /v1/whatsapp/sessions/{id}/qr.

---

List Sessions

GET /v1/whatsapp/sessions

Returns all sessions for the authenticated user.

cURL

curl https://sendapi.co/v1/whatsapp/sessions \
  -H "Authorization: Bearer sk_live_123456789"

Node.js

const sessions = await client.whatsapp.sessions.list();

Response

{
  "data": [
    {
      "id": "sess_01H8BKF...Z2T",
      "name": "Support Bot",
      "status": "connected",
      "phone_number": "+447700900000",
      "last_seen_at": "2026-03-09T14:55:00Z",
      "message_count": 1402,
      "created_at": "2026-03-09T14:30:00Z"
    }
  ],
  "meta": { "total": 1, "page": 1, "per_page": 25 }
}

---

Get a Session

GET /v1/whatsapp/sessions/{id}

Returns details for a single session.

curl https://sendapi.co/v1/whatsapp/sessions/sess_01H8BKF...Z2T \
  -H "Authorization: Bearer sk_live_123456789"

---

Get QR Code

GET /v1/whatsapp/sessions/{id}/qr

Returns a fresh QR code for an unpaired session. The previous QR code is invalidated.

{
  "qr_code": "data:image/png;base64,iVBORw0KGgoAAAA...",
  "expires_at": "2026-03-09T14:32:00Z"
}

---

Delete a Session

DELETE /v1/whatsapp/sessions/{id}

Disconnects the session and removes all associated credentials. This action is irreversible — the phone number can be re-paired by creating a new session.

curl -X DELETE https://sendapi.co/v1/whatsapp/sessions/sess_01H8BKF...Z2T \
  -H "Authorization: Bearer sk_live_123456789"

{ "deleted": true, "id": "sess_01H8BKF...Z2T" }

---

Session Statuses

Status	Description
pending	Session created, waiting for QR scan
connected	Phone paired and online
disconnected	Session lost, auto-reconnect in progress
failed	Reconnection failed after max retries