WhatsApp REST API server with a web dashboard. Run multiple instances on the same server, each on its own port.
Run this in the directory where you want to use WhatsBridge:
macOS / Linux:
curl -fsSL https://raw.githubusercontent.com/kdrcetintas/whatsbridge/main/scripts/install.sh | bashWindows (PowerShell):
iex (iwr "https://raw.githubusercontent.com/kdrcetintas/whatsbridge/main/scripts/install.ps1").ContentDownloads the correct binary for your platform into the current directory.
Download the binary for your platform from Releases:
| Platform | File |
|---|---|
| Windows | whatsbridge-vX.X.X-win-x64.exe |
| Linux | whatsbridge-vX.X.X-linux-x64 |
| macOS (Apple Silicon) | whatsbridge-vX.X.X-macos-arm64 |
On Linux/macOS, make it executable: chmod +x whatsbridge-*
git clone https://github.com/kdrcetintas/whatsbridge.git
cd whatsbridge
npm install
npm run package # → bin/whatsbridge-vX.X.X-<platform>-<arch>whatsbridge initPrompts for port, username, password. Creates whatsbridge.config.json in the current directory. Run once per instance.
whatsbridge startStarts the server and opens the dashboard in your browser. Scan the QR code with WhatsApp to connect.
Runtime data is stored in a data/ subfolder next to the config:
my-instance/
├── whatsbridge.config.json
└── data/
├── auth_info/ ← WhatsApp session
├── whatsbridge.db ← message database
└── logs/ ← daily log files
# Windows (run as Administrator)
whatsbridge service install
# Linux (requires sudo)
sudo whatsbridge service installRuns WhatsBridge in the background and starts automatically on boot.
All endpoints require ?api_key=YOUR_KEY as a query parameter.
Returns the current connection status.
curl "http://localhost:3000/api/status?api_key=YOUR_KEY"{ "status": "connected", "hasQR": false, "queue": { "length": 0, "nextSendDelay": 0 } }Sends a text message.
curl -X POST "http://localhost:3000/api/send?api_key=YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"phone":"905xxxxxxxxx","message":"Hello!"}'| Field | Type | Description |
|---|---|---|
phone |
string | Phone number with country code, no + |
message |
string | Text message |
allowQueuing |
boolean | Queue and return immediately instead of waiting |
Sends an image from a URL.
curl -X POST "http://localhost:3000/api/send-image?api_key=YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"phone":"905xxxxxxxxx","imageUrl":"https://example.com/photo.jpg","caption":"Hi"}'| Field | Type | Description |
|---|---|---|
phone |
string | Phone number with country code, no + |
imageUrl |
string | Publicly accessible image URL |
caption |
string | Optional caption |
allowQueuing |
boolean | Same as /api/send |
Lists sent/received messages.
curl "http://localhost:3000/api/messages?api_key=YOUR_KEY&limit=50&offset=0"Query params: limit, offset, status (queued/sending/sent/failed), phone.
Returns a single message by internal ID.
Returns message counts.
{ "sent": 42, "received": 10, "queued": 0, "failed": 1 }By default (allowQueuing: false) the API waits for WhatsApp to confirm delivery before responding. Pass allowQueuing: true to queue the message and return immediately — useful for bulk sends.
A rate limit of 5 seconds between sends is enforced to avoid bans. Pending messages survive restarts.
Each instance runs in its own directory with its own config and WhatsApp session.
mkdir account-1 && cd account-1 && whatsbridge init # port 3000
mkdir account-2 && cd account-2 && whatsbridge init # port 3001Available at http://localhost:PORT after starting. Log in with the username and password set during init.
Tabs: Status — Send Message — Logs — API Docs
ISC