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	No	A human-readable label for this session (e.g., "Support Bot"). Auto-generated if omitted.

Per-session webhook URLs are not supported — webhooks are configured at the account level (see Webhooks).

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": 8,
  "session_key": "wa_34_1774206887_cdd5cd",
  "name": "Support Bot",
  "status": "pending",
  "qr_code": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
  "phone_number": null,
  "created_at": "2026-03-09T14:30:00Z"
}

The session id (integer) is what you pass to /v1/whatsapp/send and all other WhatsApp endpoints. The session_key is an internal identifier used by the sidecar — you usually don't need it.

Render the qr_code as an image and scan it with WhatsApp on the device you want to connect. 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": 8,
      "session_key": "wa_34_1774206887_cdd5cd",
      "name": "Support Bot",
      "status": "connected",
      "phone_number": "447700900000",
      "messages_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/8 \
  -H "Authorization: Bearer sk_live_123456789"

---

Get QR Code

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

Returns a fresh QR code for an unpaired session.

{
  "qr_code": "data:image/png;base64,iVBORw0KGgoAAAA..."
}

---

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/8 \
  -H "Authorization: Bearer sk_live_123456789"

{
  "success": true,
  "data": null,
  "meta": {
    "request_id": "9b84375a-5c4b-46e3-9542-c992a952897c",
    "timestamp": "2026-03-09T14:30:00.000000Z"
  }
}

---

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