Developer documentation

Send messages through an authorized QR-linked WhatsApp session and receive signed event webhooks.

Quickstart

Create a QR channel in the dashboard, scan it from WhatsApp Linked devices, wait for connected, then create an API key.

Authentication

Use either a Bearer token or the X-API-Key header.

Authorization: Bearer cb_live_your_key

Send text

POST /api/v1/messages/text

curl -X POST https://chat.example.com/api/v1/messages/text \
  -H "Authorization: Bearer cb_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "channel_id": "chn_xxxxx",
    "to": "8801XXXXXXXXX",
    "text": "Hello"
  }'

The recipient must use international digits without +, spaces, or punctuation.

Accepted response

{
  "ok": true,
  "message_id": "true_8801...@c.us_..."
}

Send PDF and media

Use one of these endpoints: /api/v1/messages/document, /image, /video, /audio, /voice, or /sticker.

curl -X POST https://chat.example.com/api/v1/messages/document \
  -H "Authorization: Bearer cb_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "channel_id": "chn_xxxxx",
    "to": "8801XXXXXXXXX",
    "file_url": "https://provider.example.com/files/3330616008.pdf",
    "filename": "3330616008.pdf",
    "caption": "Your PDF is ready"
  }'

You can send base64 plus mimetype instead of file_url. The default file limit is controlled by MAX_MEDIA_MB.

Incoming media webhook

Incoming files are stored privately. The signed webhook contains a temporary download URL:

{
  "event": "message.received",
  "data": {
    "type": "document",
    "has_media": true,
    "media": {
      "id": "med_xxxxx",
      "filename": "request.pdf",
      "mimetype": "application/pdf",
      "size": 142860,
      "expires_at": "2026-08-04T15:00:00.000Z",
      "download_url": "https://chat.example.com/api/v1/media/med_xxxxx?token=..."
    }
  }
}

Outgoing webhooks

Configure a URL under Channel settings. ChatBridge sends JSON events for session status, incoming messages, outgoing messages and acknowledgements.

{
  "id": "evt_xxxxx",
  "event": "message.received",
  "timestamp": "2026-08-03T13:45:00.000Z",
  "channel": {
    "id": 1,
    "public_id": "chn_xxxxx",
    "name": "Main support",
    "provider": "webjs",
    "number": "8801XXXXXXXXX"
  },
  "data": {
    "message_id": "false_...",
    "from": "8801XXXXXXXXX@c.us",
    "type": "chat",
    "body": "Hello",
    "has_media": false
  }
}

Delivery is retried and logged in the dashboard.

Verify signature

The X-ChatBridge-Signature header is an HMAC-SHA256 signature of the exact raw JSON body.

const crypto = require('crypto');

const expected = 'sha256=' + crypto
  .createHmac('sha256', process.env.CHATBRIDGE_WEBHOOK_SECRET)
  .update(rawBody)
  .digest('hex');

Common errors

400  Invalid input
401  Missing or invalid API key
404  Channel not found
409  QR is not ready yet
429  Rate limit exceeded
502  WhatsApp session disconnected or send failed

POST /api/v1/automation/requests/:request_id/complete
Authorization: Bearer cb_live_...
Content-Type: application/json

{
  "file_url": "https://provider.example/file.pdf",
  "filename": "request.pdf",
  "caption": "আপনার PDF প্রস্তুত হয়েছে।"
}

POST /api/v1/automation/complete

{
  "request_key": "3330616008",
  "channel_id": "chn_...",
  "file_url": "https://provider.example/3330616008.pdf"
}