Sign inRequest access

Sessions

A session is one WhatsApp number linked to Warsita as a linked device, like WhatsApp Web on a computer. Your workspace's plan sets how many sessions it can have. The endpoints on this page need a personal access token.

curl https://api.warsita.com/v1/sessions \
  -H "Authorization: Bearer $WARSITA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Support line", "phone": "+6281234567890"}'

The answer holds the session and its API key, which is shown only here:

{
  "session": { "id": "ses_3kV9mQ2pX7aL0zR5tN8w", "name": "Support line", "status": "need_scan", "linked": false, "…": "…" },
  "api_key": "wsk_…"
}

Then link the phone in one of two ways:

  • QR code. GET /v1/sessions/{id}/qr returns {"status", "qr_code"}. qr_code is WhatsApp's raw pairing string: draw it with any QR library and scan it in WhatsApp → Linked devices → Link a device. WhatsApp replaces it every 20 to 60 seconds, so keep polling, or listen to the event stream below.
  • Pairing code. POST /v1/sessions/{id}/pairing-code with {"phone": "+6281234567890"} (or nothing, to use the session's phone) returns {"pair_code": "ABCD1234"}. On the phone choose Link with phone number instead and type it.

When the phone confirms, the session becomes connected and phone is filled in.

Keep the phone online. The session works through the phone's WhatsApp. If the phone stays off or offline for about 14 days, or someone logs the device out under Linked devices, WhatsApp ends the link and the session becomes logged_out.

Status

status Meaning
need_scan Waiting for a QR scan or a pairing code.
connecting Connecting to WhatsApp.
connected Linked and online: messages are sent and received.
disconnected The connection dropped; Warsita reconnects by itself.
logged_out The number was logged out, usually from the phone (Linked devices → Log out). Link it again.
banned WhatsApp banned the number.
paused The workspace's plan has ended. The number stays linked and reconnects when the plan is renewed.

status_reason explains the last change in words. GET /v1/sessions/{id}/logs lists the last 100 session events (connected, disconnected, QR ready, and so on).

Live updates

GET /v1/sessions/{id}/events is a server-sent events stream. The first state event is the current state, and another follows each time the status, QR code or phone changes:

event: state
data: {"session_id":"ses_3kV9…","workspace_id":"…","type":"state","status":"need_scan","qr_code":"2@Xq9…"}

A : ping comment every 25 seconds keeps it open; reconnect when it closes. To get the same changes on your server without holding a connection, subscribe the webhook to session.status and qrcode.updated.

Connect, restart, disconnect

Request Effect
POST /v1/sessions/{id}/connect Connects a linked session, or starts pairing again.
POST /v1/sessions/{id}/restart Drops the connection and reconnects, without a new scan.
POST /v1/sessions/{id}/disconnect Logs the number out. The session stays; linking it again needs a new scan.
DELETE /v1/sessions/{id} Logs the number out and deletes the session.

The first three answer 202 at once; follow the result through the status.

Settings

Send settings when you create a session, or change them with PATCH /v1/sessions/{id}. settings is replaced as a whole, so send every key:

{
  "settings": {
    "account_protection": true,
    "message_logging": false,
    "read_incoming": false,
    "reject_calls": false,
    "always_online": false,
    "ignore_groups": false,
    "ignore_broadcasts": true,
    "ignore_channels": true
  }
}
Setting When on
account_protection Shows "typing…" and waits 1 to 4 seconds before each message, like a person would. On by default.
message_logging Keeps message content and webhook bodies after delivery. Off by default: Warsita keeps only the status.
read_incoming Marks incoming messages as read.
reject_calls Rejects incoming calls.
always_online Shows the account as online.
ignore_groups, ignore_broadcasts, ignore_channels No webhooks for messages from groups, from broadcast lists and statuses, or from channels.

Proxy

To connect a session through your own proxy, set proxy_url to an http://, https:// or socks5:// URL on a public host name, for example socks5://user:pass@proxy.example.com:1080. IP addresses and internal names are refused. Changing the proxy of a linked session reconnects it; "proxy_url": "" removes it.

Avoiding bans

Warsita uses WhatsApp's linked-device protocol, not the official WhatsApp Business Platform, and WhatsApp bans numbers that behave like spam. To keep a number healthy:

  • Message people who expect it: customers, members, your own team. Do not send to bought or scraped lists.
  • Keep account_protection on, and send at a human pace.
  • Use a number that has a real history of normal use, and add a proxy in the recipients' country if you send from far away.
  • Watch for banned and logged_out through the session.status webhook.
NextSend Messages