Connect a number

A session is one linked WhatsApp number. You link the phone once — by scanning a QR code or entering a pairing code — and the gateway keeps the connection alive after that, reconnecting on its own if it drops.

Linking takes three steps:

1. Create the session.
2. Link your phone with a QR code or a pairing code.
3. Confirm the session reached the working status.

1. Create the session

In the dashboard, open your organization's sessions page, create a session, and give it a label.

To do it from code, send POST /sessions with an optional label and a start flag. See create a session.

A new session starts in the scan_qr_code status, meaning it is waiting for a phone to link.

2. Link the phone

Pick whichever is easier on the phone. Both link the same way WhatsApp's own "Linked devices" feature does.

Option A: Scan a QR code

The session produces a QR code string that refreshes about every 20 seconds. The dashboard draws the QR image for you and swaps it each time it refreshes.

On the phone, open WhatsApp → Linked devices → Link a device, then scan the code shown in the dashboard.

To fetch the current code from code instead, call get the QR code. The endpoint returns JSON with a code string — your client renders the QR image from that string.

Option B: Enter a pairing code

If scanning is awkward, request a pairing code tied to the phone number. WhatsApp returns a short code (for example ABCD-1234) that you type into the phone.

Request the code:

curl -X POST https://your-gateway/api/v1/sessions/{id}/pairing-code \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"phone":"628123456789"}'

The phone value is the number in international format — digits only, no + and no spaces.

On the phone, open WhatsApp → Linked devices → Link a device → Link with phone number instead, then enter the code.

See request a pairing code.

3. Confirm it linked

Once the phone accepts, the session moves to the working status. A session can be in any of these statuses:

The dashboard updates the status live. From code, you can poll the session or subscribe to session.status on the realtime WebSocket.

Next

With a session in the working status, you can send messages and receive events.