Linking a WhatsApp number

A session is one WhatsApp number that YASend keeps connected for you, 24/7, as a linked device of that number (like WhatsApp Web).

Create and connect

curl -X POST https://api.yasend.dev/v1/sessions -H "Authorization: Bearer $YASEND_KEY" \
  -H "Content-Type: application/json" -d '{"name": "Support line"}'
curl -X POST https://api.yasend.dev/v1/sessions/$SESSION_ID/connect -H "Authorization: Bearer $YASEND_KEY"

Then link the phone in one of two ways.

With the QR code

GET /v1/sessions/{id}/qr supports three formats:

`format`	Returns
`json` (default)	`{"qrCode": "<base64 PNG>"}`
`png`	The image itself
`string`	`{"qrString": "..."}`, to render the QR code yourself

To scan it: WhatsApp → Settings → Linked devices → Link a device.

The code changes about every 20 seconds, so poll the endpoint while showing it.

Response	Meaning
`202 QR_PENDING`	The QR code is still being generated
`409 ALREADY_AUTHENTICATED`	The number is already linked

With a pairing code (no camera needed)

curl -X POST https://api.yasend.dev/v1/sessions/$SESSION_ID/pairing-code \
  -H "Authorization: Bearer $YASEND_KEY" -H "Content-Type: application/json" \
  -d '{"phoneNumber": "963912345678"}'
# → {"status": "connecting", "pairingCode": "ABCD-EFGH"}

On the phone: Linked devices → Link a device → Link with phone number instead, then type the code.

Status

GET /v1/sessions/{id} returns the session. GET /v1/sessions/{id}/status returns the live state.

`status`	Meaning
`pending`	Created, never connected
`connecting`	Waiting for the QR code to be scanned, or for the pairing code
`connected`	Linked and online: you can send
`reconnecting`	Temporarily offline. YASend reconnects by itself
`disconnected`	Stopped (you disconnected it, or your plan paused it). Still linked
`logged_out`	Unlinked from the phone. Connect again and scan a new QR code
`conflict`	The number was opened as WhatsApp Web somewhere else
`banned_suspected`	WhatsApp appears to have restricted the number
`crashed`	It failed to start repeatedly. Check the events timeline, then connect again

statusReason explains the last change, and GET /v1/sessions/{id}/events returns the full timeline. Subscribe to the session.alert webhook to hear about problems as they happen.

Staying connected

Server restarts: your number stays linked. YASend stores the login securely and reconnects by itself after restarts and network drops, without a new QR scan.
Logging out: YASend never logs a number out on its own. Only deleting the session does that.

Call	Effect
`POST /v1/sessions/{id}/pause`	Refuses sends at once (`SESSION_PAUSED`). Incoming messages and webhooks keep flowing
`POST /v1/sessions/{id}/resume`	Allows sending again
`POST /v1/sessions/{id}/disconnect`	Closes the connection but stays linked. Connect again any time, without scanning
`DELETE /v1/sessions/{id}`	Logs the number out of WhatsApp and deletes the session and its key

Plans and suspension

Situation	What happens
Trial or plan expires	The sessions disconnect at once (still linked), and sending is refused with `402 SUBSCRIPTION_EXPIRED` during a short grace period
Grace period ends	Sending and connecting are refused with `402 SUBSCRIPTION_SUSPENDED` until you renew
You renew	Sessions reconnect by themselves, no QR scan
You downgrade to fewer sessions	The newest sessions over the limit are paused the same way

Health

GET /v1/sessions/{id}/health returns:

the number's health score;
its warm-up day and today's cap;
anything currently blocking sends.

See Safety & warm-up.