WhatsApp API (whapi.cloud compatible)

v1.0.0

Base URL

http://localhost:3005

Authentication

API key required (X-API-Key header or Bearer token)

curl -H "X-API-Key: YOUR_KEY" http://localhost:3005/channels

Channel ID

All endpoints except /channels require channelId

?channelId=xxx  or  X-Channel-Id: xxx

Channels

GET /channels List channels with today message counts and a short health summary (level ok/warning/critical, summary, first recommendation) ▼

RESPONSE

{ success, channels: ChannelInfo[], total } — ChannelInfo.health: { level, summary, hint }

EXAMPLE

curl -H "X-API-Key: $KEY" http://localhost:3005/channels

{
  "success": true,
  "channels": [
    {
      "id": "channel-123",
      "name": "Sales",
      "status": "connected",
      "phone": "79991234567",
      "health": {
        "level": "ok",
        "summary": "Подключён 6 ч, за сутки без разрывов",
        "hint": null
      }
    }
  ],
  "total": 1
}

POST /channels Create a new channel ▼

REQUEST BODY / QUERY PARAMS

Name	Type	Required	Description
name	string	required	Channel name `Sales Team`
department	string	optional	Department name `Sales`
autoConnect	boolean	optional	Auto-connect on startup `true`

EXAMPLE

curl -X POST -H "X-API-Key: $KEY" -d '{"name":"Sales"}' http://localhost:3005/channels

{
  "success": true,
  "data": {
    "id": "channel-123",
    "name": "Sales"
  }
}

GET /channels/:id Get channel details ▼

PATH PARAMETERS

Name	Type	Required	Description
id	string	required	Channel ID `"channel-123"`

PUT /channels/:id Update channel ▼

PATH PARAMETERS

Name	Type	Required	Description
id	string	required	Channel ID

REQUEST BODY / QUERY PARAMS

Name	Type	Required	Description
name	string	optional	New name
department	string	optional	New department
autoConnect	boolean	optional	Auto-connect setting

DELETE /channels/:id Delete channel and disconnect session ▼

PATH PARAMETERS

Name	Type	Required	Description
id	string	required	Channel ID

POST /channels/:id/connect Start connection (generates QR code) ▼

PATH PARAMETERS

Name	Type	Required	Description
id	string	required	Channel ID

RESPONSE

{ success: true, status: "qr", qr: "base64..." }

POST /channels/:id/connect-phone Connect via phone number (pairing code) ▼

PATH PARAMETERS

Name	Type	Required	Description
id	string	required	Channel ID

REQUEST BODY / QUERY PARAMS

Name	Type	Required	Description
phoneNumber	string	required	Phone number with country code `+79991234567`

RESPONSE

{ success: true, pairingCode: "ABCD-1234" }

POST /channels/:id/disconnect Disconnect session (keeps auth) ▼

PATH PARAMETERS

Name	Type	Required	Description
id	string	required	Channel ID

POST /channels/:id/logout Logout and delete session ▼

PATH PARAMETERS

Name	Type	Required	Description
id	string	required	Channel ID

GET /channels/:id/diagnostics Channel health for operators (connection, sending limits, receiving, webhooks, Russian recommendations) plus raw socket diagnostics for developers ▼

PATH PARAMETERS

Name	Type	Required	Description
id	string	required	Channel ID

RESPONSE

{ success, health: { level, summary, connection, sending, receiving, webhooks, recommendations[] }, diagnostics: SocketDiagnostics, recommendations: string[], dedup }

EXAMPLE

curl -H "X-API-Key: $KEY" http://localhost:3005/channels/channel-123/diagnostics

{
  "success": true,
  "health": {
    "level": "ok",
    "summary": "Подключён 6 ч, за сутки без разрывов",
    "recommendations": [
      "Канал работает штатно."
    ]
  }
}

GET /channels/:id/status Get connection status ▼

PATH PARAMETERS

Name	Type	Required	Description
id	string	required	Channel ID

RESPONSE

{ status: "connected" | "disconnected" | "connecting" | "qr" }

GET /channels/:id/qr Get QR code as base64 JSON ▼

PATH PARAMETERS

Name	Type	Required	Description
id	string	required	Channel ID

RESPONSE

{ success: true, qr: "data:image/png;base64,..." }

GET /channels/:id/qr/image Get QR code as PNG image ▼

PATH PARAMETERS

Name	Type	Required	Description
id	string	required	Channel ID

RESPONSE

image/png

GET /channels/:id/chats Get all chats for channel ▼

PATH PARAMETERS

Name	Type	Required	Description
id	string	required	Channel ID

GET /channels/:id/chats/:chatId/messages Get messages from chat ▼

PATH PARAMETERS

Name	Type	Required	Description
id	string	required	Channel ID
chatId	string	required	Chat JID `"79991234567@s.whatsapp.net"`

REQUEST BODY / QUERY PARAMS

Name	Type	Required	Description
limit	number	optional	Max messages `50`
offset	number	optional	Skip N messages `0`

POST /channels/:id/messages/send-immediate Send message immediately (bypasses queue) ▼

PATH PARAMETERS

Name	Type	Required	Description
id	string	required	Channel ID

REQUEST BODY / QUERY PARAMS

Name	Type	Required	Description
phone	string	required	Recipient phone `79991234567`
message	string	required	Message text `Hello!`

EXAMPLE

curl -X POST -H "X-API-Key: $KEY" -d '{"phone":"79991234567","message":"Hi!"}' http://localhost:3005/channels/ch-1/messages/send-immediate

POST /channels/:id/messages/image Send image message ▼

PATH PARAMETERS

Name	Type	Required	Description
id	string	required	Channel ID

REQUEST BODY / QUERY PARAMS

Name	Type	Required	Description
to	string	required	Recipient phone or JID `79991234567`
media	string	required	URL or base64 image `https://example.com/image.jpg`
caption	string	optional	Image caption

POST /channels/:id/messages/video Send video message ▼

PATH PARAMETERS

Name	Type	Required	Description
id	string	required	Channel ID

REQUEST BODY / QUERY PARAMS

Name	Type	Required	Description
to	string	required	Recipient
media	string	required	URL or base64 video
caption	string	optional	Video caption

POST /channels/:id/messages/document Send document/file ▼

PATH PARAMETERS

Name	Type	Required	Description
id	string	required	Channel ID

REQUEST BODY / QUERY PARAMS

Name	Type	Required	Description
to	string	required	Recipient
media	string	required	URL or base64 file
filename	string	optional	File name `report.pdf`
mimetype	string	optional	MIME type `application/pdf`

POST /channels/:id/messages/location Send location ▼

PATH PARAMETERS

Name	Type	Required	Description
id	string	required	Channel ID

REQUEST BODY / QUERY PARAMS

Name	Type	Required	Description
to	string	required	Recipient
latitude	number	required	Latitude `55.7558`
longitude	number	required	Longitude `37.6173`
name	string	optional	Location name `Moscow`
address	string	optional	Address `Red Square`

POST /channels/:id/messages/contact Send vCard contact ▼

PATH PARAMETERS

Name	Type	Required	Description
id	string	required	Channel ID

REQUEST BODY / QUERY PARAMS

Name	Type	Required	Description
to	string	required	Recipient
contact.fullName	string	required	Contact name `John Doe`
contact.phone	string	required	Contact phone `+79991234567`

GET /channels/:id/webhooks List webhooks of the channel ▼

PATH PARAMETERS

Name	Type	Required	Description
id	string	required	Channel ID

POST /channels/:id/webhooks Add a webhook to the channel ▼

PATH PARAMETERS

Name	Type	Required	Description
id	string	required	Channel ID

REQUEST BODY / QUERY PARAMS

Name	Type	Required	Description
url	string	required	Webhook URL `https://example.com/webhook`
events	string[]	required	Events to receive `["message.received","message.sent"]`
secret	string	optional	HMAC secret for signing
enabled	boolean	optional	Enable webhook `true`

Messages

POST /messages/text Send text message (whapi.cloud compatible) ▼

REQUEST BODY / QUERY PARAMS

Name	Type	Required	Description
channelId	string	required	Channel ID (or X-Channel-Id header)
to	string	required	Recipient phone `79991234567`
body	string	required	Message text `Hello World!`

EXAMPLE

curl -X POST -H "X-API-Key: $KEY" -d '{"channelId":"ch-1","to":"79991234567","body":"Hello!"}' http://localhost:3005/messages/text

{
  "success": true,
  "messageId": "BAE5123..."
}

POST /messages/image Send image ▼

REQUEST BODY / QUERY PARAMS

Name	Type	Required	Description
channelId	string	required	Channel ID
to	string	required	Recipient phone
media	string	required	Image URL or base64 `https://example.com/photo.jpg`
caption	string	optional	Image caption

POST /messages/video Send video ▼

REQUEST BODY / QUERY PARAMS

Name	Type	Required	Description
channelId	string	required	Channel ID
to	string	required	Recipient phone
media	string	required	Video URL or base64
caption	string	optional	Video caption

POST /messages/audio Send audio file ▼

REQUEST BODY / QUERY PARAMS

Name	Type	Required	Description
channelId	string	required	Channel ID
to	string	required	Recipient phone
media	string	required	Audio URL or base64

POST /messages/voice Send voice message (PTT) ▼

REQUEST BODY / QUERY PARAMS

Name	Type	Required	Description
channelId	string	required	Channel ID
to	string	required	Recipient phone
media	string	required	OGG audio URL or base64

POST /messages/document Send document/file ▼

REQUEST BODY / QUERY PARAMS

Name	Type	Required	Description
channelId	string	required	Channel ID
to	string	required	Recipient phone
media	string	required	File URL or base64
filename	string	optional	Filename `report.pdf`
mimetype	string	optional	MIME type

POST /messages/sticker Send sticker ▼

REQUEST BODY / QUERY PARAMS

Name	Type	Required	Description
channelId	string	required	Channel ID
to	string	required	Recipient phone
media	string	required	WebP sticker URL or base64

POST /messages/location Send location ▼

REQUEST BODY / QUERY PARAMS

Name	Type	Required	Description
channelId	string	required	Channel ID
to	string	required	Recipient phone
latitude	number	required	Latitude `55.7558`
longitude	number	required	Longitude `37.6173`
name	string	optional	Location name
address	string	optional	Address text

POST /messages/contact Send vCard contact ▼

REQUEST BODY / QUERY PARAMS

Name	Type	Required	Description
channelId	string	required	Channel ID
to	string	required	Recipient phone
contact	object	required	Contact object { fullName, phone }

EXAMPLE

curl -X POST -d '{"channelId":"ch-1","to":"79991234567","contact":{"fullName":"John","phone":"+123456"}}' http://localhost:3005/messages/contact

POST /messages/gif Send animated GIF ▼

REQUEST BODY / QUERY PARAMS

Name	Type	Required	Description
channelId	string	required	Channel ID
to	string	required	Recipient phone
media	string	required	GIF/MP4 URL or base64
caption	string	optional	Caption

POST /messages/short Send PTV (video note/circle) ▼

REQUEST BODY / QUERY PARAMS

Name	Type	Required	Description
channelId	string	required	Channel ID
to	string	required	Recipient phone
media	string	required	Video URL or base64

POST /messages/poll Send poll ▼

REQUEST BODY / QUERY PARAMS

Name	Type	Required	Description
channelId	string	required	Channel ID
to	string	required	Recipient phone
question	string	required	Poll question `What is your choice?`
options	string[]	required	Poll options `["Option A","Option B","Option C"]`
multiSelect	boolean	optional	Allow multiple answers `false`

EXAMPLE

curl -X POST -d '{"channelId":"ch-1","to":"799...","question":"Rate?","options":["1","2","3","4","5"]}' http://localhost:3005/messages/poll

POST /messages/link-preview Send URL with link preview ▼

REQUEST BODY / QUERY PARAMS

Name	Type	Required	Description
channelId	string	required	Channel ID
to	string	required	Recipient phone
url	string	required	URL to send `https://example.com`
title	string	optional	Link title
description	string	optional	Link description

POST /messages/live-location Send live location ▼

REQUEST BODY / QUERY PARAMS

Name	Type	Required	Description
channelId	string	required	Channel ID
to	string	required	Recipient phone
latitude	number	required	Latitude
longitude	number	required	Longitude
duration	number	optional	Duration in seconds `3600`

POST /messages/contact-list Send multiple contacts ▼

REQUEST BODY / QUERY PARAMS

Name	Type	Required	Description
channelId	string	required	Channel ID
to	string	required	Recipient phone
contacts	array	required	Array of { fullName, phone }

POST /messages/forward Forward message to recipients ▼

REQUEST BODY / QUERY PARAMS

Name	Type	Required	Description
channelId	string	required	Channel ID
chatId	string	required	Source chat JID
messageId	string	required	Message ID to forward
to	string[]	required	Recipients array `["79991234567","79997654321"]`

GET /messages/list Get all messages ▼

REQUEST BODY / QUERY PARAMS

Name	Type	Required	Description
channelId	string	required	Channel ID (query param)
limit	number	optional	Max messages `50`
offset	number	optional	Skip count `0`

GET /messages/list/:chatId Get messages from specific chat ▼

PATH PARAMETERS

Name	Type	Required	Description
chatId	string	required	Chat JID

REQUEST BODY / QUERY PARAMS

Name	Type	Required	Description
channelId	string	required	Channel ID
limit	number	optional	Max messages

PUT /messages/:id/star Star/unstar message ▼

PATH PARAMETERS

Name	Type	Required	Description
id	string	required	Message ID

REQUEST BODY / QUERY PARAMS

Name	Type	Required	Description
channelId	string	required	Channel ID
chatId	string	required	Chat JID
star	boolean	required	Star status `true`

POST /messages/:id/pin Pin message ▼

PATH PARAMETERS

Name	Type	Required	Description
id	string	required	Message ID

REQUEST BODY / QUERY PARAMS

Name	Type	Required	Description
channelId	string	required	Channel ID
chatId	string	required	Chat JID
duration	number	optional	Pin duration (seconds) `86400`

DELETE /messages/:id/pin Unpin message ▼

PATH PARAMETERS

Name	Type	Required	Description
id	string	required	Message ID

REQUEST BODY / QUERY PARAMS

Name	Type	Required	Description
channelId	string	required	Channel ID
chatId	string	required	Chat JID

PUT /messages/:id/reaction React to message with emoji ▼

PATH PARAMETERS

Name	Type	Required	Description
id	string	required	Message ID

REQUEST BODY / QUERY PARAMS

Name	Type	Required	Description
channelId	string	required	Channel ID
chatId	string	required	Chat JID
emoji	string	required	Emoji reaction `👍`

DELETE /messages/:id Delete message ▼

PATH PARAMETERS

Name	Type	Required	Description
id	string	required	Message ID

REQUEST BODY / QUERY PARAMS

Name	Type	Required	Description
channelId	string	required	Channel ID
chatId	string	required	Chat JID
forEveryone	boolean	optional	Delete for everyone `true`

Chats

GET /chats Get all chats ▼

REQUEST BODY / QUERY PARAMS

Name	Type	Required	Description
channelId	string	required	Channel ID (query param)

GET /chats/:id Get chat info ▼

PATH PARAMETERS

Name	Type	Required	Description
id	string	required	Chat JID

REQUEST BODY / QUERY PARAMS

Name	Type	Required	Description
channelId	string	required	Channel ID

POST /chats/:id/archive Archive chat ▼

PATH PARAMETERS

Name	Type	Required	Description
id	string	required	Chat JID

REQUEST BODY / QUERY PARAMS

Name	Type	Required	Description
channelId	string	required	Channel ID

DELETE /chats/:id/archive Unarchive chat ▼

PATH PARAMETERS

Name	Type	Required	Description
id	string	required	Chat JID

REQUEST BODY / QUERY PARAMS

Name	Type	Required	Description
channelId	string	required	Channel ID

POST /chats/:id/pin Pin chat ▼

PATH PARAMETERS

Name	Type	Required	Description
id	string	required	Chat JID

REQUEST BODY / QUERY PARAMS

Name	Type	Required	Description
channelId	string	required	Channel ID

DELETE /chats/:id/pin Unpin chat ▼

PATH PARAMETERS

Name	Type	Required	Description
id	string	required	Chat JID

REQUEST BODY / QUERY PARAMS

Name	Type	Required	Description
channelId	string	required	Channel ID

POST /chats/:id/mute Mute chat notifications ▼

PATH PARAMETERS

Name	Type	Required	Description
id	string	required	Chat JID

REQUEST BODY / QUERY PARAMS

Name	Type	Required	Description
channelId	string	required	Channel ID
duration	number	optional	Mute duration (seconds) `86400`

DELETE /chats/:id/mute Unmute chat ▼

PATH PARAMETERS

Name	Type	Required	Description
id	string	required	Chat JID

REQUEST BODY / QUERY PARAMS

Name	Type	Required	Description
channelId	string	required	Channel ID

POST /chats/:id/read Mark chat as read ▼

PATH PARAMETERS

Name	Type	Required	Description
id	string	required	Chat JID

REQUEST BODY / QUERY PARAMS

Name	Type	Required	Description
channelId	string	required	Channel ID

DELETE /chats/:id Delete chat ▼

PATH PARAMETERS

Name	Type	Required	Description
id	string	required	Chat JID

REQUEST BODY / QUERY PARAMS

Name	Type	Required	Description
channelId	string	required	Channel ID

Contacts

GET /contacts Get all contacts ▼

REQUEST BODY / QUERY PARAMS

Name	Type	Required	Description
channelId	string	required	Channel ID (query param)

POST /contacts/check Check if phones have WhatsApp ▼

REQUEST BODY / QUERY PARAMS

Name	Type	Required	Description
channelId	string	required	Channel ID
phones	string[]	required	Phone numbers to check `["79991234567","79997654321"]`

EXAMPLE

curl -X POST -d '{"channelId":"ch-1","phones":["79991234567"]}' http://localhost:3005/contacts/check

{
  "success": true,
  "data": [
    {
      "phone": "79991234567",
      "exists": true,
      "jid": "79991234567@s.whatsapp.net"
    }
  ]
}

GET /contacts/blocked Get blocked contacts ▼

REQUEST BODY / QUERY PARAMS

Name	Type	Required	Description
channelId	string	required	Channel ID

POST /contacts/:phone/block Block a contact ▼

PATH PARAMETERS

Name	Type	Required	Description
phone	string	required	Phone number

REQUEST BODY / QUERY PARAMS

Name	Type	Required	Description
channelId	string	required	Channel ID

POST /contacts/:phone/unblock Unblock a contact ▼

PATH PARAMETERS

Name	Type	Required	Description
phone	string	required	Phone number

REQUEST BODY / QUERY PARAMS

Name	Type	Required	Description
channelId	string	required	Channel ID

GET /contacts/:phone/profile Get contact profile picture & status ▼

PATH PARAMETERS

Name	Type	Required	Description
phone	string	required	Phone number

REQUEST BODY / QUERY PARAMS

Name	Type	Required	Description
channelId	string	required	Channel ID

Groups

GET /groups Get all groups ▼

REQUEST BODY / QUERY PARAMS

Name	Type	Required	Description
channelId	string	required	Channel ID (query param)

POST /groups Create new group ▼

REQUEST BODY / QUERY PARAMS

Name	Type	Required	Description
channelId	string	required	Channel ID
name	string	required	Group name `My Group`
participants	string[]	required	Initial members `["79991234567"]`

GET /groups/:id Get group info and members ▼

PATH PARAMETERS

Name	Type	Required	Description
id	string	required	Group JID

REQUEST BODY / QUERY PARAMS

Name	Type	Required	Description
channelId	string	required	Channel ID

PATCH /groups/:id Update group name/description ▼

PATH PARAMETERS

Name	Type	Required	Description
id	string	required	Group JID

REQUEST BODY / QUERY PARAMS

Name	Type	Required	Description
channelId	string	required	Channel ID
name	string	optional	New group name
description	string	optional	New description

DELETE /groups/:id Leave group ▼

PATH PARAMETERS

Name	Type	Required	Description
id	string	required	Group JID

REQUEST BODY / QUERY PARAMS

Name	Type	Required	Description
channelId	string	required	Channel ID

POST /groups/:id/participants Add participants to group ▼

PATH PARAMETERS

Name	Type	Required	Description
id	string	required	Group JID

REQUEST BODY / QUERY PARAMS

Name	Type	Required	Description
channelId	string	required	Channel ID
participants	string[]	required	Phone numbers to add

DELETE /groups/:id/participants Remove participants from group ▼

PATH PARAMETERS

Name	Type	Required	Description
id	string	required	Group JID

REQUEST BODY / QUERY PARAMS

Name	Type	Required	Description
channelId	string	required	Channel ID
participants	string[]	required	Phone numbers to remove

POST /groups/:id/participants/promote Promote members to admin ▼

PATH PARAMETERS

Name	Type	Required	Description
id	string	required	Group JID

REQUEST BODY / QUERY PARAMS

Name	Type	Required	Description
channelId	string	required	Channel ID
participants	string[]	required	Phone numbers to promote

POST /groups/:id/participants/demote Demote admins to members ▼

PATH PARAMETERS

Name	Type	Required	Description
id	string	required	Group JID

REQUEST BODY / QUERY PARAMS

Name	Type	Required	Description
channelId	string	required	Channel ID
participants	string[]	required	Phone numbers to demote

GET /groups/:id/invite Get group invite link ▼

PATH PARAMETERS

Name	Type	Required	Description
id	string	required	Group JID

REQUEST BODY / QUERY PARAMS

Name	Type	Required	Description
channelId	string	required	Channel ID

POST /groups/:id/invite/revoke Revoke invite link (generate new) ▼

PATH PARAMETERS

Name	Type	Required	Description
id	string	required	Group JID

REQUEST BODY / QUERY PARAMS

Name	Type	Required	Description
channelId	string	required	Channel ID

Stories

GET /stories Get status stories ▼

REQUEST BODY / QUERY PARAMS

Name	Type	Required	Description
channelId	string	required	Channel ID

POST /stories/text Post text story ▼

REQUEST BODY / QUERY PARAMS

Name	Type	Required	Description
channelId	string	required	Channel ID
text	string	required	Story text `Hello World!`
backgroundColor	string	optional	Background color `#FF5733`
font	number	optional	Font type (0-5) `0`

POST /stories/image Post image story ▼

REQUEST BODY / QUERY PARAMS

Name	Type	Required	Description
channelId	string	required	Channel ID
media	string	required	Image URL or base64
caption	string	optional	Caption

POST /stories/video Post video story ▼

REQUEST BODY / QUERY PARAMS

Name	Type	Required	Description
channelId	string	required	Channel ID
media	string	required	Video URL or base64
caption	string	optional	Caption

DELETE /stories/:id Delete story ▼

PATH PARAMETERS

Name	Type	Required	Description
id	string	required	Story ID

REQUEST BODY / QUERY PARAMS

Name	Type	Required	Description
channelId	string	required	Channel ID

Labels

GET /labels Get all labels ▼

REQUEST BODY / QUERY PARAMS

Name	Type	Required	Description
channelId	string	required	Channel ID

POST /labels Create label ▼

REQUEST BODY / QUERY PARAMS

Name	Type	Required	Description
channelId	string	required	Channel ID
name	string	required	Label name `VIP`
color	number	optional	Color index (0-20) `1`

DELETE /labels/:id Delete label ▼

PATH PARAMETERS

Name	Type	Required	Description
id	string	required	Label ID

REQUEST BODY / QUERY PARAMS

Name	Type	Required	Description
channelId	string	required	Channel ID

POST /labels/:id/chats Add chat to label ▼

PATH PARAMETERS

Name	Type	Required	Description
id	string	required	Label ID

REQUEST BODY / QUERY PARAMS

Name	Type	Required	Description
channelId	string	required	Channel ID
chatId	string	required	Chat JID

DELETE /labels/:id/chats/:chatId Remove chat from label ▼

PATH PARAMETERS

Name	Type	Required	Description
id	string	required	Label ID
chatId	string	required	Chat JID

REQUEST BODY / QUERY PARAMS

Name	Type	Required	Description
channelId	string	required	Channel ID

Business

GET /business/profile Get business profile ▼

REQUEST BODY / QUERY PARAMS

Name	Type	Required	Description
channelId	string	required	Channel ID

RESPONSE

{ description, email, websites[], address, category }

PATCH /business/profile Update business profile ▼

REQUEST BODY / QUERY PARAMS

Name	Type	Required	Description
channelId	string	required	Channel ID
description	string	optional	Business description
email	string	optional	Business email
website	string	optional	Website URL
address	string	optional	Business address

GET /business/categories Get available business categories ▼

RESPONSE

{ categories: [...] }

Users

GET /users Get own profile ▼

REQUEST BODY / QUERY PARAMS

Name	Type	Required	Description
channelId	string	required	Channel ID

RESPONSE

{ name, status, picture }

PATCH /users Update profile ▼

REQUEST BODY / QUERY PARAMS

Name	Type	Required	Description
channelId	string	required	Channel ID
name	string	optional	Display name
status	string	optional	About text

PUT /users/picture Update profile picture ▼

REQUEST BODY / QUERY PARAMS

Name	Type	Required	Description
channelId	string	required	Channel ID
image	string	required	Image URL or base64

Media

GET /media/:id Download media by ID ▼

PATH PARAMETERS

Name	Type	Required	Description
id	string	required	Media ID

REQUEST BODY / QUERY PARAMS

Name	Type	Required	Description
channelId	string	required	Channel ID

POST /media/upload Upload media file (multipart/form-data) ▼

REQUEST BODY / QUERY PARAMS

Name	Type	Required	Description
channelId	string	required	Channel ID
file	File	required	File to upload (multipart)

RESPONSE

{ mediaId, url, mimetype }

Newsletters

GET /newsletters Get subscribed newsletters/channels ▼

REQUEST BODY / QUERY PARAMS

Name	Type	Required	Description
channelId	string	required	Channel ID

POST /newsletters Create newsletter ▼

REQUEST BODY / QUERY PARAMS

Name	Type	Required	Description
channelId	string	required	Channel ID
name	string	required	Newsletter name
description	string	optional	Description

POST /newsletters/:id/messages Send message to newsletter ▼

PATH PARAMETERS

Name	Type	Required	Description
id	string	required	Newsletter JID

REQUEST BODY / QUERY PARAMS

Name	Type	Required	Description
channelId	string	required	Channel ID
text	string	optional	Text message
media	string	optional	Media URL or base64

Communities

GET /communities Get all communities ▼

REQUEST BODY / QUERY PARAMS

Name	Type	Required	Description
channelId	string	required	Channel ID

GET /communities/:id Get community details ▼

PATH PARAMETERS

Name	Type	Required	Description
id	string	required	Community JID

REQUEST BODY / QUERY PARAMS

Name	Type	Required	Description
channelId	string	required	Channel ID

Analytics

GET /analytics/overview Get analytics overview ▼

REQUEST BODY / QUERY PARAMS

Name	Type	Required	Description
channelId	string	optional	Filter by channel

RESPONSE

{ totalMessages, sentMessages, receivedMessages, todayMessages }

GET /analytics/daily Get daily message counts ▼

REQUEST BODY / QUERY PARAMS

Name	Type	Required	Description
channelId	string	optional	Filter by channel
days	number	optional	Number of days `7`

GET /analytics/by-hour Get hourly distribution ▼

REQUEST BODY / QUERY PARAMS

Name	Type	Required	Description
channelId	string	optional	Filter by channel

GET /analytics/by-weekday Get weekday distribution ▼

REQUEST BODY / QUERY PARAMS

Name	Type	Required	Description
channelId	string	optional	Filter by channel

GET /analytics/channels Get per-channel stats ▼

RESPONSE

[{ channelId, name, today, week, total }]

GET /analytics/trends Get message trends ▼

REQUEST BODY / QUERY PARAMS

Name	Type	Required	Description
days	number	optional	Days to analyze `14`

Backups

GET /backups Backup schedule, storage usage and list of archives ▼

RESPONSE

{ success, enabled, retentionDays, hour, dir, count, totalSizeBytes, lastBackupAt, nextRunAt, backups: [{ name, sizeBytes, createdAt, preRestore }] }

EXAMPLE

curl -H "X-API-Key: $KEY" http://localhost:3005/backups

{
  "success": true,
  "enabled": true,
  "retentionDays": 7,
  "count": 2,
  "backups": [
    {
      "name": "whapi-20260906T030000Z.tar.gz",
      "sizeBytes": 254331,
      "createdAt": 1788653000000,
      "preRestore": false
    }
  ]
}

POST /backups Create a backup right now (whapi.db snapshot + channels.json) and prune expired ones ▼

RESPONSE

{ success, backup: { name, sizeBytes, createdAt }, pruned: string[] }

EXAMPLE

curl -X POST -H "X-API-Key: $KEY" http://localhost:3005/backups

{
  "success": true,
  "backup": {
    "name": "whapi-20260906T131500Z.tar.gz",
    "sizeBytes": 254331
  },
  "pruned": []
}

GET /backups/:name/download Download a backup archive (.tar.gz) ▼

RESPONSE

application/gzip stream

EXAMPLE

curl -H "X-API-Key: $KEY" -O -J http://localhost:3005/backups/whapi-20260906T030000Z.tar.gz/download

DELETE /backups/:name Delete a backup archive ▼

RESPONSE

{ success, deleted }

POST /backups/:name/restore Restore data from a backup stored on the server. Channels disconnect, data is replaced, channels reconnect. A pre-restore snapshot is taken automatically ▼

RESPONSE

{ success, source, manifest, safetyBackup }

EXAMPLE

curl -X POST -H "X-API-Key: $KEY" http://localhost:3005/backups/whapi-20260906T030000Z.tar.gz/restore

{
  "success": true,
  "safetyBackup": "whapi-pre-restore-20260906T131500Z.tar.gz"
}

POST /backups/restore Upload an archive (raw body, application/octet-stream) and restore from it ▼

RESPONSE

{ success, source: "upload", sizeBytes, manifest, safetyBackup }

EXAMPLE

curl -X POST -H "X-API-Key: $KEY" -H "Content-Type: application/octet-stream" --data-binary @whapi-20260906T030000Z.tar.gz http://localhost:3005/backups/restore

System

GET /health Health check (no auth required) ▼

RESPONSE

{ status, timestamp, database, redis, channels, auth }

GET /settings Get API documentation (JSON) ▼

RESPONSE

Full API documentation object

GET /docs API documentation page (HTML, no auth) ▼

RESPONSE

HTML documentation page