WA Bot Server API

Complete REST API reference. All endpoints accept and return JSON. All /api/* routes require a valid Bearer token.

Base URL http://localhost:3000

shield Authentication

All /api/* endpoints require authentication. Include your token in every request:

Authorization: Bearer <your-token>

📌 Get your token by calling POST /auth/register or POST /auth/login.

📌 Tokens are long-lived — they never expire unless you reset your password.

📌 Resetting your password generates a new token, invalidating all old sessions.

📌 Each user has isolated data — messages, webhooks, stats, and WhatsApp sessions are fully separated.

POST /auth/register Create a new account ▶

Request Body

Param	Type		Description
email	string	Required	Your email address
password	string	Required	Min 6 characters

Example

            
curl -X POST http://localhost:3000/auth/register \
  -H "Content-Type: application/json" \
  -d '{ "email": "you@example.com", "password": "secret123" }'
          

Response

{
  "success": true,
  "token": "a1b2c3d4e5f6...",
  "user": { "id": "uuid-here", "email": "you@example.com" }
}
          

POST /auth/login Sign in and get token ▶

Request Body

Param	Type		Description
email	string	Required	Your email address
password	string	Required	Your password

Example

            
curl -X POST http://localhost:3000/auth/login \
  -H "Content-Type: application/json" \
  -d '{ "email": "you@example.com", "password": "secret123" }'
          

GET /auth/me Get current user info (requires token) ▶

Example

curl http://localhost:3000/auth/me \ -H "Authorization: Bearer YOUR_TOKEN"

Response

{ "id": "uuid", "email": "you@example.com" }
          

POST /auth/forgot-password Request OTP (logged to server console) ▶

Request Body

{ "email": "you@example.com" }

💡 The 6-digit OTP will appear in your server console. Valid for 15 minutes. Max 5 attempts.

POST /auth/reset-password Reset password with OTP ▶

Request Body

{
  "email": "you@example.com",
  "otp": "123456",
  "newPassword": "newSecret123"
}
          

⚠️ Resets your token — all existing sessions are invalidated. You'll receive a new token in the response.

POST /api/send-message Send a message to a phone number ▶

Request Body

Param	Type		Description
number	string	Required	Phone number with country code (e.g. `254712345678`)
message	string	Required	The message text to send

Example

            
curl -X POST http://localhost:3000/api/send-message \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{ "number": "254712345678", "message": "Hello from the bot!" }'
          

POST /api/send-group-message Send a message to a group ▶

Example

            
curl -X POST http://localhost:3000/api/send-group-message \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{ "groupId": "120363012345@g.us", "message": "Hello group!" }'
          

GET /api/messages Get recent message log ▶

Example

curl http://localhost:3000/api/messages?limit=10 \ -H "Authorization: Bearer YOUR_TOKEN"

GET /api/groups List all joined groups ▶

Example

curl http://localhost:3000/api/groups \ -H "Authorization: Bearer YOUR_TOKEN"

POST /api/join-group Join group via invite link ▶

Example

            
curl -X POST http://localhost:3000/api/join-group \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{ "inviteLink": "https://chat.whatsapp.com/ABC123" }'
          

POST /api/leave-group Leave a group ▶

Example

            
curl -X POST http://localhost:3000/api/leave-group \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{ "groupId": "120363012345@g.us" }'
          

POST /api/add-to-group Add participants to a group ▶

Example

            
curl -X POST http://localhost:3000/api/add-to-group \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{ "groupId": "120363012345@g.us", "participants": ["254712345678"] }'
          

GET /api/hooks List registered webhooks ▶

Example

curl http://localhost:3000/api/hooks \ -H "Authorization: Bearer YOUR_TOKEN"

POST /api/hooks/register Register a webhook URL ▶

Example

            
curl -X POST http://localhost:3000/api/hooks/register \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{ "url": "https://example.com/webhook", "name": "My App" }'
          

Webhook Payload

When a message is received, the following JSON is POSTed to your URL:

{
  "id": "false_254712345678@c.us_3EB0...",
  "from": "254712345678@c.us",
  "body": "Hello!",
  "timestamp": "2026-02-23T12:00:00.000Z",
  "type": "received",
  "contactName": "John",
  "isGroup": false
}
          

DELETE /api/hooks/unregister Remove a webhook ▶

Example

            
curl -X DELETE http://localhost:3000/api/hooks/unregister \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{ "id": "m1abc12" }'
          

GET /api/status Bot connection status + QR code ▶

Example

curl http://localhost:3000/api/status \ -H "Authorization: Bearer YOUR_TOKEN"

Response

{
  "status": "ready",  // "disconnected" | "qr" | "initializing" | "ready"
  "qr": null,        // base64 data URL when status is "qr"
  "info": {
    "pushname": "My Bot",
    "phone": "254712345678",
    "platform": "android"
  }
}
          

GET /api/stats Dashboard statistics ▶

Example

curl http://localhost:3000/api/stats \ -H "Authorization: Bearer YOUR_TOKEN"

Response

{
  "messagesSent": 42,
  "messagesReceived": 128,
  "groupsJoined": 3,
  "groupsLeft": 1,
  "webhookCount": 2
}
          

📥 Inbox & Conversations

A WhatsApp/email-style view built from the message log: messages are grouped by conversation, with each conversation's most recent message surfaced, newest first. chat is a contact or group JID (e.g. 12345@s.whatsapp.net or 12345-67890@g.us).

GET	`/api/inbox`	`?enrich=true&limit=` — conversation list + last message; `enrich` adds profile picture, name & about/topic
GET	`/api/conversation`	`?chat=&limit=` — messages of one conversation (oldest first)
GET	`/api/conversation/actions`	`?chat=` — actions available for the contact/group
POST	`/api/conversation/action`	`chat`, `action`, …params

Actions — contacts: block, unblock, subscribe_presence. Groups: exit, set_name, set_description, set_photo, announce, lock, invite_link, add/remove/promote/demote.

curl -X POST http://localhost:3000/api/conversation/action \
  -H "Authorization: Bearer YOUR_TOKEN" -H "Content-Type: application/json" \
  -d '{"chat":"12345-67890@g.us","action":"set_name","name":"New group name"}'

Realtime new messages still arrive over the WebSocket (message events); these endpoints serve the cached history and the conversation list.

📎 Media & Rich Messages

Media fields (image/video/audio/...) accept an https:// URL, a data: URI, or a raw base64 string. to accepts a phone number or a full JID.

POST	`/api/send-image`	`to`, `image`, `caption`
POST	`/api/send-video`	`to`, `video`, `caption`, `gifPlayback`
POST	`/api/send-audio`	`to`, `audio`, `ptt` (voice note)
POST	`/api/send-document`	`to`, `document`, `filename`, `caption`, `mimetype`
POST	`/api/send-sticker`	`to`, `sticker` (WebP)
POST	`/api/send-location`	`to`, `latitude`, `longitude`, `name`, `address`
POST	`/api/send-contact`	`to`, `displayName`, `phone` or `vcard`
POST	`/api/send-poll`	`to`, `name`, `options[]`, `selectableCount`

curl -X POST http://localhost:3000/api/send-image \
  -H "Authorization: Bearer YOUR_TOKEN" -H "Content-Type: application/json" \
  -d '{"to":"254712345678","image":"https://picsum.photos/600","caption":"Hi 👋"}'

✏️ Message Actions & Presence

For reactions / deletes on someone else's message, pass participant (group sender) and fromMe:false.

POST	`/api/reply-message`	`to`, `messageId`, `participant`, `text`, `quotedText`
POST	`/api/send-reaction`	`to`, `messageId`, `emoji`, `fromMe` (empty emoji removes)
POST	`/api/edit-message`	`to`, `messageId`, `newText`
POST	`/api/revoke-message`	`to`, `messageId`, `participant`, `fromMe` (delete for everyone)
POST	`/api/mark-read`	`chat`, `sender`, `messageIds[]`
POST	`/api/presence`	`presence`: `available` / `unavailable`
POST	`/api/chat-presence`	`to`, `state`: `composing`/`paused`, `media`
POST	`/api/subscribe-presence`	`jid`

👥 Group & Community Management

GET	`/api/group-info`	`?groupId=`
POST	`/api/create-group`	`name`, `participants[]`
POST	`/api/group/participants`	`groupId`, `action` (add/remove/promote/demote), `participants[]`
POST	`/api/group/name`	`groupId`, `name`
POST	`/api/group/topic`	`groupId`, `topic`
POST	`/api/group/photo`	`groupId`, `image` (empty removes)
POST	`/api/group/announce`	`groupId`, `announce`
POST	`/api/group/locked`	`groupId`, `locked`
GET	`/api/group/invite-link`	`?groupId=&reset=`
GET	`/api/group/info-from-link`	`?link=`
GET	`/api/group/join-requests`	`?groupId=`
POST	`/api/group/join-requests`	`groupId`, `action` (approve/reject), `participants[]`
POST	`/api/group/member-add-mode`	`groupId`, `mode`
POST	`/api/group/disappearing`	`groupId`, `seconds`
GET	`/api/group/subgroups`	`?communityId=`
POST	`/api/group/link` · `/api/group/unlink`	`parent`, `child`

📇 Contacts, Profile & Privacy

POST	`/api/check-number`	`numbers[]` → is on WhatsApp
GET	`/api/user-info`	`?jids=` (csv) → status, picture id, devices
GET	`/api/profile-picture`	`?jid=&preview=`
GET	`/api/business-profile`	`?jid=`
GET	`/api/user-devices`	`?jids=` (csv)
GET	`/api/contacts`	local contact cache
GET	`/api/blocklist`	list blocked users
POST	`/api/block` · `/api/unblock`	`jid`
GET	`/api/privacy-settings`	read privacy settings
POST	`/api/set-status`	`status` (your "about" text)

📰 Channels (Newsletters)

GET	`/api/newsletters`	followed channels
GET	`/api/newsletter/info`	`?jid=`
GET	`/api/newsletter/info-from-invite`	`?key=`
POST	`/api/newsletter/create`	`name`, `description`
POST	`/api/newsletter/follow` · `/unfollow`	`jid`
POST	`/api/newsletter/mute`	`jid`, `mute`

⬇️ Download Media from Chats

Incoming media (image/video/audio/document/sticker) is cached in memory as it arrives. Download it by message id; the response is a base64 dataUri you can preview or save. Only recently received media is available (cache is bounded and cleared on restart).

GET /api/download-media ?messageId= → { mediaType, mimetype, filename, size, dataUri }

curl http://localhost:3000/api/download-media?messageId=ABCD1234 \
  -H "Authorization: Bearer YOUR_TOKEN"

🔌 Realtime WebSocket

Connect to /ws for a live push stream instead of polling. Authenticate with a Bearer header, a ?token= query param, or the wa_token cookie. Every frame is a JSON envelope { event, data, timestamp }; a status snapshot is sent on connect.

Events: status, pair_success, message, receipt, presence, chat_presence, group_info, joined_group, picture, call.

const ws = new WebSocket(`ws://localhost:3000/ws?token=${'$'}{token}`);
ws.onmessage = (e) => {
  const { event, data, timestamp } = JSON.parse(e.data);
  console.log(event, data); // status | message | receipt | presence | ...
};