API Documentation — WA Bot Server

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

Request Body

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

Example Request

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

Response

{
  "success": true,
  "message": {
    "id": "true_254712345678@c.us_3EB0...",
    "from": "me",
    "to": "254712345678@c.us",
    "body": "Hello from the bot!",
    "timestamp": "2026-02-21T12:00:00.000Z",
    "type": "sent"
  }
}
            

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

Request Body

Parameter	Type		Description
groupId	string	Required	Group ID (e.g. `120363012345@g.us`). Get from `/api/groups`
message	string	Required	The message text to send

Example Request

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

Response

{
  "success": true,
  "message": {
    "id": "true_120363012345@g.us_3EB0...",
    "from": "me",
    "to": "120363012345@g.us",
    "body": "Hello group!",
    "type": "sent",
    "isGroup": true
  }
}
            

GET /api/messages Get recent message log ▶

Query Parameters

Parameter	Type		Description
limit	number		Max messages to return (default: `50`)

Example Request

curl http://localhost:3000/api/messages?limit=10

Response

[
  {
    "id": "true_254712345678@c.us_3EB0...",
    "from": "254712345678@c.us",
    "body": "Hey!",
    "timestamp": "2026-02-21T12:00:00.000Z",
    "type": "received",
    "contactName": "John",
    "isGroup": false
  }
]
            

GET /api/groups List all joined groups ▶

Example Request

curl http://localhost:3000/api/groups

Response

[
  {
    "id": "120363012345@g.us",
    "name": "Dev Team",
    "participantCount": 12,
    "isReadOnly": false
  }
]
            

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

Request Body

Parameter	Type		Description
inviteLink	string	Required	WhatsApp invite URL (e.g. `https://chat.whatsapp.com/ABC123`)

Example Request

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

Response

{ "success": true, "result": "120363012345@g.us" }
            

POST /api/leave-group Leave a group ▶

Request Body

Parameter	Type		Description
groupId	string	Required	The group ID to leave (e.g. `120363012345@g.us`)

Example Request

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

Response

{ "success": true, "result": { "success": true, "groupId": "120363012345@g.us" } }
            

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

Request Body

Parameter	Type		Description
groupId	string	Required	The group ID
participants	string[]	Required	Array of phone numbers to add

Example Request

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

Response

{ "success": true, "result": { ... } }
            

GET /api/hooks List registered webhooks ▶

Example Request

curl http://localhost:3000/api/hooks

Response

[
  {
    "id": "m1abc12",
    "url": "https://example.com/webhook",
    "name": "My App",
    "createdAt": "2026-02-21T12:00:00.000Z"
  }
]
            

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

Request Body

Parameter	Type		Description
url	string	Required	Webhook URL to receive POST requests on incoming messages
name	string		Friendly name for the webhook (defaults to the URL)

Example Request

              
curl -X POST http://localhost:3000/api/hooks/register \
  -H "Content-Type: application/json" \
  -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",
  "to": "254700000000@c.us",
  "body": "Hello!",
  "timestamp": "2026-02-21T12:00:00.000Z",
  "type": "received",
  "contactName": "John",
  "isGroup": false,
  "groupName": null
}
            

DELETE /api/hooks/unregister Remove a webhook ▶

Request Body

Parameter	Type		Description
id	string		The webhook ID (provide `id` or `url`)
url	string		The webhook URL to remove

Example Request

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

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

Example Request

curl http://localhost:3000/api/status

Response

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

GET /api/stats Dashboard statistics ▶

Example Request

curl http://localhost:3000/api/stats

Response

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

GET /api/tunnel Cloudflare tunnel public URL ▶

Example Request

curl http://localhost:3000/api/tunnel

Response

{ "url": "https://your-tunnel-id.trycloudflare.com" }

WA Bot Server API