API Reference
Base URL: https://api.warsita.com. Requests and answers are JSON; authenticate with Authorization: Bearer … (see Authentication).
OpenAPI
The whole API, with every field, example and webhook payload, is described in OpenAPI 3.1: openapi.yaml.
- Postman or Insomnia: import the file's URL,
https://warsita.com/openapi.yaml, to get a ready collection. Set theAuthorizationheader to your API key or token. - Client code: generate a typed client for your language with OpenAPI Generator or openapi-typescript, for example
npx openapi-typescript https://warsita.com/openapi.yaml -o warsita.d.ts.
Messages
API key, or token with session_id.
| Request | |
|---|---|
POST /v1/messages |
Send a message: text, image, video, audio, document, location or contact. 202 with the queued message. |
GET /v1/messages |
List messages, newest first. Query: limit (1–100, default 25), status, before. |
GET /v1/messages/{id} |
One message. |
POST /v1/messages/read |
Send read receipts: chat, ids, and sender in groups. 204. |
Contacts and groups
API key, or token with session_id.
| Request | |
|---|---|
POST /v1/contacts/check |
Which of up to 50 phones use WhatsApp. |
GET /v1/contacts/{jid} |
A contact's info. |
GET /v1/contacts/{jid}/picture |
A contact's profile picture URL. |
GET /v1/groups |
The number's groups. |
GET /v1/groups/{jid} |
One group with its participants. |
Sessions
Personal access token.
| Request | |
|---|---|
GET /v1/sessions |
List sessions. |
POST /v1/sessions |
Create a session: name, phone, settings, proxy_url. 201 with the session and its API key. |
GET /v1/sessions/{id} |
One session. |
PATCH /v1/sessions/{id} |
Change name, settings or proxy_url. |
DELETE /v1/sessions/{id} |
Log out and delete. 204. |
GET /v1/sessions/{id}/qr |
The current pairing QR string. |
POST /v1/sessions/{id}/pairing-code |
A pairing code for phone. |
POST /v1/sessions/{id}/connect |
Connect, or start pairing again. 202. |
POST /v1/sessions/{id}/restart |
Reconnect without a new scan. 202. |
POST /v1/sessions/{id}/disconnect |
Log the number out. 202. |
POST /v1/sessions/{id}/api-key |
Replace the session's API key. |
GET /v1/sessions/{id}/logs |
The last 100 session events. |
GET /v1/sessions/{id}/events |
Server-sent events: status and QR changes. |
DELETE /v1/sessions/{id}/messages |
Clear the finished messages. 204. |
Webhook
Personal access token.
| Request | |
|---|---|
GET /v1/sessions/{id}/webhook |
URL, secret, events, and the events you can choose. |
PUT /v1/sessions/{id}/webhook |
Set url and events. |
POST /v1/sessions/{id}/webhook/secret |
Rotate the signing secret. |
POST /v1/sessions/{id}/webhook/test |
Send a signed sample of event now. |
GET /v1/sessions/{id}/webhook/deliveries |
The last 50 deliveries. |
Webhook payloads
The data of each event. Incoming messages are described in Webhooks.
| Event | data |
|---|---|
message.sent |
message_id (msg_…), wa_message_id, to, type |
message-receipt.update |
chat, recipient, message_ids, status (delivered or read), timestamp |
messages.update |
chat, sender, message_id, text (the new text), timestamp |
messages.delete |
chat, sender, message_id, timestamp |
messages.reaction |
chat, sender, sender_phone, message_id, emoji ("" when removed), timestamp |
session.status |
status, event, and reason and phone when known |
qrcode.updated |
qr_code |
call |
call_id, from, from_phone, is_group, timestamp |
groups.update |
group, changes (any of name, topic, announce, locked), by, timestamp |
group-participants.update |
group, action (add, remove, promote, demote), participants, by, timestamp |
Health
GET /health answers {"status": "ok"} without authentication.