# whapi — WhatsApp API

> HTTP API к WhatsApp поверх Baileys (протокол WhatsApp Web multi-device).
> Пути совместимы с whapi.cloud. Описание собрано из маршрутов работающей сборки
> версии 1.0.2, поэтому соответствует тому, что развёрнуто прямо сейчас.

- Базовый URL: https://whapi.xpertnet.ai
- Аутентификация: заголовок `X-API-Key: <ключ>`, либо `Authorization: Bearer <ключ>`, либо `?api_key=<ключ>`
- Без ключа доступны только: `/health`, `/docs`, `/openapi.json`, `/llms.txt`, `/llms-full.txt`
- Ответы: `{ "success": true, ... }` или `{ "success": false, "error": "...", "error_code": "..." }`
- Лимиты HTTP: 200 запросов в минуту на IP, 30 в минуту на отправку сообщений
- Канал выбирается `?channelId=<id>` или заголовком `X-Channel-Id`; в путях `/channels/:id/*` — из пути

## Эндпоинты

### analytics — Аналитика сообщений

- `GET /analytics/by-hour` — Get hourly distribution
  - body: channelId?: string
- `GET /analytics/by-weekday` — Get weekday distribution
  - body: channelId?: string
- `GET /analytics/channels` — Get per-channel stats
  - ответ: [{ channelId, name, today, week, total }]
- `GET /analytics/daily` — Get daily message counts
  - body: channelId?: string, days?: number
- `GET /analytics/hourly` — List hourly
- `GET /analytics/overview` — Get analytics overview
  - body: channelId?: string
  - ответ: { totalMessages, sentMessages, receivedMessages, todayMessages }
- `GET /analytics/trends` — Get message trends
  - body: days?: number

### backups — Резервные копии данных

- `GET /backups` — Backup schedule, storage usage and list of archives
  - ответ: { success, enabled, retentionDays, hour, dir, count, totalSizeBytes, lastBackupAt, nextRunAt, backups: [{ name, sizeBytes, createdAt, preRestore }] }
  - пример: `curl -H "X-API-Key: $KEY" http://localhost:3005/backups`
- `POST /backups` — Create a backup right now (whapi.db snapshot + channels.json) and prune expired ones
  - ответ: { success, backup: { name, sizeBytes, createdAt }, pruned: string[] }
  - пример: `curl -X POST -H "X-API-Key: $KEY" http://localhost:3005/backups`
- `DELETE /backups/:name` — Delete a backup archive
  - ответ: { success, deleted }
- `GET /backups/:name/download` — Download a backup archive (.tar.gz)
  - ответ: application/gzip stream
  - пример: `curl -H "X-API-Key: $KEY" -O -J http://localhost:3005/backups/whapi-20260906T030000Z.tar.gz/download`
- `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
  - ответ: { success, source, manifest, safetyBackup }
  - пример: `curl -X POST -H "X-API-Key: $KEY" http://localhost:3005/backups/whapi-20260906T030000Z.tar.gz/restore`
- `POST /backups/restore` — Upload an archive (raw body, application/octet-stream) and restore from it
  - ответ: { success, source: "upload", sizeBytes, manifest, safetyBackup }
  - пример: `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`

### business — Бизнес-профиль

- `GET /business/categories` — Get available business categories
  - ответ: { categories: [...] }
- `GET /business/profile` — Get business profile
  - body: channelId: string
  - ответ: { description, email, websites[], address, category }
- `PATCH /business/profile` — Update business profile
  - body: channelId: string, description?: string, email?: string, website?: string, address?: string

### channels — Каналы: создание, подключение по QR или коду, статус, вебхуки, прокси, диагностика

- `GET /channels` — Get list of all channels
  - ответ: { success: true, data: Channel[] }
  - пример: `curl -H "X-API-Key: $KEY" http://localhost:3005/channels`
- `POST /channels` — Create a new channel
  - body: name: string, department?: string, autoConnect?: boolean
  - пример: `curl -X POST -H "X-API-Key: $KEY" -d '{"name":"Sales"}' http://localhost:3005/channels`
- `DELETE /channels/:id` — Delete channel and disconnect session
  - query: id: string
- `GET /channels/:id` — Get channel details
  - query: id: string
- `PUT /channels/:id` — Update channel
  - query: id: string
  - body: name?: string, department?: string, autoConnect?: boolean
- `PUT /channels/:id/auto-connect` — Update auto connect
- `GET /channels/:id/auto-download` — List auto download
- `PUT /channels/:id/auto-download` — Update auto download
- `GET /channels/:id/chats` — Get all chats for channel
  - query: id: string
- `GET /channels/:id/chats/:chatId/messages` — Get messages from chat
  - query: id: string, chatId: string
  - body: limit?: number, offset?: number
- `GET /channels/:id/chats/:chatId/messages/search` — List search
- `POST /channels/:id/connect` — Start connection (generates QR code)
  - query: id: string
  - ответ: { success: true, status: "qr", qr: "base64..." }
- `POST /channels/:id/connect-phone` — Connect via phone number (pairing code)
  - query: id: string
  - body: phoneNumber: string
  - ответ: { success: true, pairingCode: "ABCD-1234" }
- `POST /channels/:id/contacts/:phone/block` — Block contacts
- `POST /channels/:id/contacts/:phone/unblock` — Unblock contacts
- `GET /channels/:id/contacts/blocked` — List blocked
- `POST /channels/:id/contacts/check` — Create check
- `GET /channels/:id/diagnostics` — List diagnostics
- `POST /channels/:id/disconnect` — Disconnect session (keeps auth)
  - query: id: string
- `GET /channels/:id/groups` — List groups
- `GET /channels/:id/lid-mappings` — List lid mappings
- `POST /channels/:id/logout` — Logout and delete session
  - query: id: string
- `POST /channels/:id/messages/contact` — Send vCard contact
  - query: id: string
  - body: to: string, contact.fullName: string, contact.phone: string
- `POST /channels/:id/messages/document` — Send document/file
  - query: id: string
  - body: to: string, media: string, filename?: string, mimetype?: string
- `POST /channels/:id/messages/forward` — Forward messages
- `POST /channels/:id/messages/image` — Send image message
  - query: id: string
  - body: to: string, media: string, caption?: string
- `POST /channels/:id/messages/location` — Send location
  - query: id: string
  - body: to: string, latitude: number, longitude: number, name?: string, address?: string
- `DELETE /channels/:id/messages/queue` — Delete queue
- `GET /channels/:id/messages/queue` — List queue
- `POST /channels/:id/messages/send` — Send messages
- `POST /channels/:id/messages/send-immediate` — Send message immediately (bypasses queue)
  - query: id: string
  - body: phone: string, message: string
  - пример: `curl -X POST -H "X-API-Key: $KEY" -d '{"phone":"79991234567","message":"Hi!"}' http://localhost:3005/channels/ch-1/messages/send-immediate`
- `GET /channels/:id/messages/stats` — List stats
- `POST /channels/:id/messages/video` — Send video message
  - query: id: string
  - body: to: string, media: string, caption?: string
- `GET /channels/:id/pairing-code` — List pairing code
- `GET /channels/:id/proxy` — List proxy
- `PUT /channels/:id/proxy` — Update proxy
- `POST /channels/:id/proxy/test` — Test proxy
- `GET /channels/:id/qr` — Get QR code as base64 JSON
  - query: id: string
  - ответ: { success: true, qr: "data:image/png;base64,..." }
- `GET /channels/:id/qr/image` — Get QR code as PNG image
  - query: id: string
  - ответ: image/png
- `POST /channels/:id/resolve-lids` — Resolve lids channels
- `GET /channels/:id/status` — Get connection status
  - query: id: string
  - ответ: { status: "connected" | "disconnected" | "connecting" | "qr" }
- `GET /channels/:id/webhooks` — List webhooks of the channel
  - query: id: string
- `POST /channels/:id/webhooks` — Add a webhook to the channel
  - query: id: string
  - body: url: string, events: string[], secret?: string, enabled?: boolean
- `DELETE /channels/:id/webhooks/:webhookId` — Delete webhooks
- `PUT /channels/:id/webhooks/:webhookId` — Update webhooks
- `POST /channels/:id/webhooks/:webhookId/disable` — Disable webhooks
- `POST /channels/:id/webhooks/:webhookId/enable` — Enable webhooks
- `POST /channels/:id/webhooks/:webhookId/test` — Test webhooks
- `DELETE /channels/:id/webhooks/dlq` — Delete dlq
- `GET /channels/:id/webhooks/dlq` — List dlq
- `POST /channels/:id/webhooks/dlq/replay` — Replay dlq

### chats — Чаты: список, архив, закрепление, отметка о прочтении

- `GET /chats` — Get all chats
  - body: channelId: string
- `DELETE /chats/:chatId` — Delete chat
  - query: id: string
  - body: channelId: string
- `GET /chats/:chatId` — Get chat info
  - query: id: string
  - body: channelId: string
- `DELETE /chats/:chatId/archive` — Unarchive chat
  - query: id: string
  - body: channelId: string
- `POST /chats/:chatId/archive` — Archive chat
  - query: id: string
  - body: channelId: string
- `GET /chats/:chatId/messages` — List messages
- `GET /chats/:chatId/messages/search` — List search
- `DELETE /chats/:chatId/mute` — Unmute chat
  - query: id: string
  - body: channelId: string
- `POST /chats/:chatId/mute` — Mute chat notifications
  - query: id: string
  - body: channelId: string, duration?: number
- `DELETE /chats/:chatId/pin` — Unpin chat
  - query: id: string
  - body: channelId: string
- `POST /chats/:chatId/pin` — Pin chat
  - query: id: string
  - body: channelId: string
- `POST /chats/:chatId/read` — Mark chat as read
  - query: id: string
  - body: channelId: string

### communities — Сообщества

- `GET /communities` — Get all communities
  - body: channelId: string
- `POST /communities` — Create communities
- `GET /communities/:communityId` — Get community details
  - query: id: string
  - body: channelId: string
- `GET /communities/:communityId/groups` — List groups
- `POST /communities/:communityId/groups` — Create groups
- `DELETE /communities/:communityId/groups/:groupId` — Delete groups

### contacts — Контакты, проверка номеров, блокировки

- `GET /contacts` — Get all contacts
  - body: channelId: string
- `PUT /contacts` — Update contacts
- `DELETE /contacts/:contactId` — Delete contacts
- `GET /contacts/:contactId` — Get contacts
- `PATCH /contacts/:contactId` — Update contacts
- `POST /contacts/:contactId/block` — Block a contact
  - query: phone: string
  - body: channelId: string
- `GET /contacts/:contactId/profile` — Get contact profile picture & status
  - query: phone: string
  - body: channelId: string
- `POST /contacts/:contactId/unblock` — Unblock a contact
  - query: phone: string
  - body: channelId: string
- `GET /contacts/blocked` — Get blocked contacts
  - body: channelId: string
- `POST /contacts/check` — Check if phones have WhatsApp
  - body: channelId: string, phones: string[]
  - пример: `curl -X POST -d '{"channelId":"ch-1","phones":["79991234567"]}' http://localhost:3005/contacts/check`

### groups — Группы и участники

- `GET /groups` — Get all groups
  - body: channelId: string
- `POST /groups` — Create new group
  - body: channelId: string, name: string, participants: string[]
- `DELETE /groups/:groupId` — Leave group
  - query: id: string
  - body: channelId: string
- `GET /groups/:groupId` — Get group info and members
  - query: id: string
  - body: channelId: string
- `PATCH /groups/:groupId` — Update group name/description
  - query: id: string
  - body: channelId: string, name?: string, description?: string
- `DELETE /groups/:groupId/icon` — Delete icon
- `GET /groups/:groupId/icon` — List icon
- `PUT /groups/:groupId/icon` — Update icon
- `GET /groups/:groupId/invite` — Get group invite link
  - query: id: string
  - body: channelId: string
- `POST /groups/:groupId/invite/revoke` — Revoke invite link (generate new)
  - query: id: string
  - body: channelId: string
- `DELETE /groups/:groupId/participants` — Remove participants from group
  - query: id: string
  - body: channelId: string, participants: string[]
- `GET /groups/:groupId/participants` — List participants
- `POST /groups/:groupId/participants` — Add participants to group
  - query: id: string
  - body: channelId: string, participants: string[]
- `POST /groups/:groupId/participants/demote` — Demote admins to members
  - query: id: string
  - body: channelId: string, participants: string[]
- `POST /groups/:groupId/participants/promote` — Promote members to admin
  - query: id: string
  - body: channelId: string, participants: string[]
- `POST /groups/join` — Join groups

### labels — Метки чатов

- `GET /labels` — Get all labels
  - body: channelId: string
- `POST /labels` — Create label
  - body: channelId: string, name: string, color?: number
- `DELETE /labels/:labelId` — Delete label
  - query: id: string
  - body: channelId: string
- `GET /labels/:labelId` — Get labels
- `GET /labels/:labelId/chats` — List chats
- `POST /labels/:labelId/chats` — Add chat to label
  - query: id: string
  - body: channelId: string, chatId: string
- `DELETE /labels/:labelId/chats/:chatId` — Remove chat from label
  - query: id: string, chatId: string
  - body: channelId: string

### media — Загрузка и скачивание медиа

- `DELETE /media/:mediaId` — Delete media
- `GET /media/:mediaId` — Download media by ID
  - query: id: string
  - body: channelId: string
- `GET /media/:mediaId/info` — List info
- `POST /media/from-url` — Create from url
- `POST /media/upload` — Upload media file (multipart/form-data)
  - body: channelId: string, file: File
  - ответ: { mediaId, url, mimetype }

### messages — Отправка сообщений всех типов и операции над ними

- `DELETE /messages/:chatId/typing` — Untyping messages
- `POST /messages/:chatId/typing` — Typing messages
- `GET /messages/:id/media` — List media
- `DELETE /messages/:messageId` — Delete message
  - query: id: string
  - body: channelId: string, chatId: string, forEveryone?: boolean
- `DELETE /messages/:messageId/pin` — Unpin message
  - query: id: string
  - body: channelId: string, chatId: string
- `POST /messages/:messageId/pin` — Pin message
  - query: id: string
  - body: channelId: string, chatId: string, duration?: number
- `DELETE /messages/:messageId/react` — Delete react
- `PUT /messages/:messageId/react` — Update react
- `DELETE /messages/:messageId/reaction` — Unreaction messages
- `PUT /messages/:messageId/reaction` — React to message with emoji
  - query: id: string
  - body: channelId: string, chatId: string, emoji: string
- `PUT /messages/:messageId/read` — Read messages
- `PUT /messages/:messageId/star` — Star/unstar message
  - query: id: string
  - body: channelId: string, chatId: string, star: boolean
- `POST /messages/audio` — Send audio file
  - body: channelId: string, to: string, media: string
- `POST /messages/contact` — Send vCard contact
  - body: channelId: string, to: string, contact: object
  - пример: `curl -X POST -d '{"channelId":"ch-1","to":"79991234567","contact":{"fullName":"John","phone":"+123456"}}' http://localhost:3005/messages/contact`
- `POST /messages/contact-list` — Send multiple contacts
  - body: channelId: string, to: string, contacts: array
- `POST /messages/document` — Send document/file
  - body: channelId: string, to: string, media: string, filename?: string, mimetype?: string
- `POST /messages/forward` — Forward message to recipients
  - body: channelId: string, chatId: string, messageId: string, to: string[]
- `POST /messages/gif` — Send animated GIF
  - body: channelId: string, to: string, media: string, caption?: string
- `POST /messages/image` — Send image
  - body: channelId: string, to: string, media: string, caption?: string
- `POST /messages/link-preview` — Send URL with link preview
  - body: channelId: string, to: string, url: string, title?: string, description?: string
- `GET /messages/list` — Get all messages
  - body: channelId: string, limit?: number, offset?: number
- `GET /messages/list/:chatId` — Get messages from specific chat
  - query: chatId: string
  - body: channelId: string, limit?: number
- `POST /messages/live-location` — Send live location
  - body: channelId: string, to: string, latitude: number, longitude: number, duration?: number
- `POST /messages/location` — Send location
  - body: channelId: string, to: string, latitude: number, longitude: number, name?: string, address?: string
- `POST /messages/poll` — Send poll
  - body: channelId: string, to: string, question: string, options: string[], multiSelect?: boolean
  - пример: `curl -X POST -d '{"channelId":"ch-1","to":"799...","question":"Rate?","options":["1","2","3","4","5"]}' http://localhost:3005/messages/poll`
- `POST /messages/send-immediate` — Create send immediate
- `POST /messages/short` — Send PTV (video note/circle)
  - body: channelId: string, to: string, media: string
- `POST /messages/sticker` — Send sticker
  - body: channelId: string, to: string, media: string
- `POST /messages/text` — Send text message (whapi.cloud compatible)
  - body: channelId: string, to: string, body: string
  - пример: `curl -X POST -H "X-API-Key: $KEY" -d '{"channelId":"ch-1","to":"79991234567","body":"Hello!"}' http://localhost:3005/messages/text`
- `POST /messages/video` — Send video
  - body: channelId: string, to: string, media: string, caption?: string
- `POST /messages/voice` — Send voice message (PTT)
  - body: channelId: string, to: string, media: string

### newsletters — Каналы WhatsApp (newsletters)

- `GET /newsletters` — Get subscribed newsletters/channels
  - body: channelId: string
- `POST /newsletters` — Create newsletter
  - body: channelId: string, name: string, description?: string
- `GET /newsletters/:newsletterId` — Get newsletters
- `POST /newsletters/:newsletterId/messages` — Send message to newsletter
  - query: id: string
  - body: channelId: string, text?: string, media?: string
- `POST /newsletters/:newsletterId/subscribe` — Create subscribe
- `POST /newsletters/:newsletterId/unsubscribe` — Create unsubscribe

### presences — Присутствие и статус «печатает…»

- `GET /presences/:contactId` — Get presences
- `POST /presences/:contactId/subscribe` — Create subscribe
- `PUT /presences/me` — Update me

### stories — Статусы (истории)

- `GET /stories` — Get status stories
  - body: channelId: string
- `POST /stories` — Create stories
- `DELETE /stories/:storyId` — Delete story
  - query: id: string
  - body: channelId: string
- `POST /stories/audio` — Create audio
- `POST /stories/image` — Post image story
  - body: channelId: string, media: string, caption?: string
- `POST /stories/media` — Create media
- `POST /stories/text` — Post text story
  - body: channelId: string, text: string, backgroundColor?: string, font?: number
- `POST /stories/video` — Post video story
  - body: channelId: string, media: string, caption?: string

### system — Служебные: здоровье, метрики, документация

- `GET /docs` — API documentation page (HTML, no auth) (без ключа)
  - ответ: HTML documentation page
- `GET /health` — Health check (no auth required) (без ключа)
  - ответ: { status, timestamp, database, redis, channels, auth }
- `GET /health/details` — List details
- `GET /llms-full.txt` — List llms full.txt (без ключа)
- `GET /llms.txt` — List llms.txt (без ключа)
- `GET /metrics` — List metrics
- `DELETE /monitoring/alerts` — Delete alerts
- `GET /monitoring/alerts` — List alerts
- `POST /monitoring/alerts/:id/acknowledge` — Create acknowledge
- `POST /monitoring/alerts/acknowledge-all` — Create acknowledge all
- `GET /monitoring/alerts/critical` — List critical
- `GET /monitoring/alerts/stats` — List stats
- `GET /openapi.json` — List openapi.json (без ключа)
- `GET /settings` — Get API documentation (JSON)
  - ответ: Full API documentation object

### users — Профиль подключённого аккаунта

- `GET /users` — Get own profile
  - body: channelId: string
  - ответ: { name, status, picture }
- `PATCH /users` — Update profile
  - body: channelId: string, name?: string, status?: string
- `PUT /users/name` — Update name
- `DELETE /users/picture` — Delete picture
- `PUT /users/picture` — Update profile picture
  - body: channelId: string, image: string
- `PUT /users/status` — Update status

### webhooks — Вебхуки: мониторинг доставки, DLQ, песочница

- `POST /test-webhook/:token` — Create test webhook (без ключа)
- `GET /test-webhook/requests` — List requests
- `POST /test-webhook/send` — Send test webhook
- `GET /webhook-monitor/all-webhooks` — List all webhooks
- `DELETE /webhook-monitor/deliveries` — Delete deliveries
- `GET /webhook-monitor/deliveries` — List deliveries
- `DELETE /webhook-monitor/dlq` — Delete dlq
- `GET /webhook-monitor/dlq` — List dlq
- `POST /webhook-monitor/dlq/:id/retry` — Create retry
- `POST /webhook-monitor/dlq/retry-all` — Create retry all
- `GET /webhook-monitor/stats` — List stats
- `POST /webhook-monitor/test-webhook` — Create test webhook
- `PATCH /webhook-monitor/webhook/:channelId/:webhookId/toggle` — Update toggle

## О полноте описания

Всего путей: 204. Из них с ручным описанием: 110,
с автоматически выведенным кратким описанием: 94 (в OpenAPI помечены `x-generated-summary`).
Список путей всегда полон: он берётся из маршрутов работающей сборки, а не из отдельного файла.