API Reference — WonderChat

Аутентификация

Auth

POST /auth/register Регистрация

Тело запроса

Поле	Тип	Описание
email	req	Email адрес
password	req	Пароль (min 8 символов)
name	req	Имя пользователя

Ответ 201

{ "token": "eyJhbGci...", "refreshToken": "eyJhbGci...", "user": { "id": "u1", "email": "user@ex.ru", "name": "Иван" } }

POST /auth/login Авторизация

Тело запроса

Поле	Тип	Описание
email	req	Email
password	req	Пароль

Пример запроса

curl https://panel.wonderchat.ru/api/v1/auth/login \ -X POST -H 'Content-Type: application/json' \ -d '{"email":"user@ex.ru","password":"Secret123!"}'

Ответ 200

{ "token": "eyJhbGci...", "refreshToken": "eyJhbGci..." }

POST /auth/refresh Обновить токен

Поле	Тип	Описание
refreshToken	req	refresh токен из login

Ответ 200

{ "token": "eyJhbGci..." }

GET /auth/me Текущий пользователь

🔒 Требует Bearer токен

Ответ 200

{ "id": "u1", "email": "user@ex.ru", "name": "Иван", "role": "admin" }

POST /auth/logout Выход

🔒 Требует Bearer токен

Отозвание текущей сессии. Используйте /auth/logout-all для выхода со всех устройств.

Управление

Account

GET /account Информация об аккаунте

🔒 Bearer токен

Ответ 200

{ "id": "acc_1", "name": "Моя Компания", "plan": "pro", "createdAt": "2026-01-01T00:00:00Z" }

PATCH /account Обновить аккаунт

🔒 Bearer токен

Поле	Тип	Описание
name	opt	Название аккаунта

GET /account/users Список пользователей

🔒 Bearer токен

Ответ 200

[ { "id": "u1", "name": "Иван", "email": "i@ex.ru", "role": "admin" } ]

POST /account/users Создать пользователя

🔒 Bearer токен

Поле	Тип	Описание
email	req	Email нового пользователя
name	req	Имя
password	req	Пароль
role	opt	`admin` \| `operator` (деф. operator)

Каналы

Channels

GET /channels Все каналы

🔒 Bearer токен

Ответ 200

[{ "id": "ch1", "name": "Мой Telegram", "type": "telegram", "status": "online", "createdAt": "2026-01-01T00:00:00Z" }]

POST /channels Создать канал

🔒 Bearer токен

Поле	Тип	Описание
name	req	Название канала
type	req	`telegram` \| `telegram_bot` \| `whatsapp` \| `waba` \| `vk` \| `instagram` \| `max` \| `max_personal`
credentials	req	Объект с параметрами канала

credentials для telegram

{ "apiId": 12345678, "apiHash": "abc123...", "phone": "+79001234567" }

credentials для telegram_bot

{ "token": "1234567890:AAFxxx..." }

credentials для waba

{ "phoneNumberId": "1234567890", "accessToken": "EAABxx..." }

credentials для vk

{ "token": "vk1.a.xxx" // groupId определяется автоматически }

credentials для max_personal (личный аккаунт)

// Токен можно передать при создании, а QR-подключение выполняется через // POST /channels/:id/max-qr/start и GET /channels/:id/max-qr/status

PATCH /channels/:id Обновить канал

🔒 Bearer токен

Поле	Тип	Описание
name	opt	Новое название
credentials	opt	Обновить креденшиалы (мержится с существующими)
healthCheckInterval	opt	Автопереподключение в минутах: `0..1440`

ВКонтакте: credentials мержатся с существующими (токен не теряется), а при передаче confirmationCode/secretKey адаптер перезапускается автоматически через Redis.

DELETE /channels/:id Удалить канал

🔒 Bearer токен

Отключает канал и удаляет его. Ответ 204 No Content.

POST /channels/:id/connect Подключить канал

🔒 Bearer токен

Для Telegram запускает auth flow (code/2FA), для остальных каналов публикует команду подключения в Redis. Для WhatsApp отдельный QR запрашивается через POST /channels/:id/qr, для MAX Personal — через POST /channels/:id/max-qr/start.

Ответ для Telegram (требуется код)

{ "status": "code_required" }

Ответ для обычного подключения

{ "status": "connecting", "message": "Channel connection initiated" }

POST /channels/:id/qr Обновить QR

🔒 Bearer токен

Только для WhatsApp. Генерирует новый QR-код.

POST /channels/:id/max-qr/start Старт MAX Personal QR

🔒 Bearer токен

Только для каналов max_personal. Запускает QR-авторизацию и возвращает QR URL.

Ответ 200

{ "qrUrl": "https://max.ru/qr/track_xxx", "expiresAt": "2026-04-17T12:34:56.000Z" }

GET /channels/:id/max-qr/status Статус MAX Personal QR

🔒 Bearer токен

Проверяет прогресс QR-авторизации: pending, connected, expired, failed.

Ответ 200

{ "status": "pending" }

Диалоги

Conversations

GET /conversations Список диалогов

🔒 Bearer токен

Query параметры

Параметр	Тип	Описание
channelId	opt	Фильтр по каналу
status	opt	`open` \| `closed`
unread	opt	`true` — только непрочитанные
search	opt	Текстовый поиск
page	opt	Страница (деф. 1)
limit	opt	Диалогов на странице (деф. 30)

Ответ 200

{ "data": [{ "id": "c1", "contact": {...}, "lastMessage": {...}, "unreadCount": 3 }], "total": 42, "page": 1 }

GET /conversations/:id Один диалог

🔒 Bearer токен

PATCH /conversations/:id Обновить диалог

🔒 Bearer токен

Поле	Тип	Описание
status	opt	`open` \| `closed`
assignedTo	opt	ID пользователя

GET /conversations/:id/messages Сообщения

🔒 Bearer токен

Query параметры

Параметр	Тип	Описание
before	opt	ID сообщения (пагинация назад)
limit	opt	Деф. 50

Ответ 200

[{ "id": "msg1", "type": "text", "text": "Здравствуйте!", "direction": "in", // "in" | "out" "status": "delivered", "createdAt": "2026-04-11T10:00:00Z" }]

POST /conversations/:id/messages Отправить сообщение

🔒 Bearer токен

Поле	Тип	Описание
type	req	`text` \| `image` \| `video` \| `document` \| `audio`
text	opt	Текст сообщения
mediaUrl	opt	URL медиа из `/conversations/upload`
replyToId	opt	ID ответного сообщения

Пример

{ "type": "text", "text": "Ваш заказ оформлен!" }

POST /conversations/upload Загрузить файл

🔒 Bearer токен

Ьлёт multipart/form-data с полем file. Юакже принимает JSON с полем url (если файл уже в сети).

Ответ 200

{ "url": "https://...", "mimeType": "image/jpeg", "size": 204800 }

POST /conversations/:id/read Отметить прочитанным

🔒 Bearer токен

Отмечает все сообщения диалога прочитанными, обнуляет unreadCount. Ответ 200.

Контакты

Contacts

GET /contacts Список контактов

🔒 Bearer токен

Query

Параметр	Тип	Описание
search	opt	Поиск по имени/телефону
tag	opt	Фильтр по тегу
page / limit	opt	Пагинация

POST /contacts Создать контакт

🔒 Bearer токен

Поле	Тип	Описание
name	req	Имя
phone	opt	Юелефон
email	opt	Email
tags	opt	Массив строк
externalId	opt	ID во внешней системе

PATCH /contacts/:id Обновить

🔒 Bearer токен

Юе же поля, что при создании, все опциональны.

POST /contacts/merge Объединить дубликаты

🔒 Bearer токен

Поле	Тип	Описание
primaryId	req	Главная запись
mergeIds	req	Массив ID для объединения

GET /contacts/tags/all Все теги

🔒 Bearer токен

Возвращает отсортированный массив всех уникальных тегов контактов аккаунта.

Response 200
["VIP", "рассылка-июнь", "холодный"]

Шаблоны

Templates

GET /templates Список шаблонов

🔒 Bearer токен

Ответ 200

[{ "id": "tpl1", "name": "привет", "content": "Здравствуйте, {{name}}!" }]

POST /templates Создать шаблон

🔒 Bearer токен

Поле	Тип	Описание
name	req	Название для поиска
content	req	Текст (поддерживает `{{var}}`)

DELETE /templates/:id Удалить

🔒 Bearer токен

204 No Content.

Рассылки

Broadcasts

GET /broadcasts Список рассылок

🔒 Bearer токен

Возвращает все рассылки аккаунта.

POST /broadcasts Создать рассылку

🔒 Bearer токен · owner / admin

Тело запроса

Поле	Тип	Описание
name	req	Название (1-200 символов)
channelId	req	ID канала отправки
message	req	Объект: `{ type, text, media }`
message.type	req	`text` \| `image` \| `video` \| `document`
message.text	opt	Текст сообщения (до 4096 символов)
message.media	opt	`{ url, contentType }` — медиа-вложение
recipients	req	Объект: `{ mode, tags?, contactIds? }`
recipients.mode	req	`all` \| `tags` \| `contacts`
recipients.tags	opt	Массив тегов (при mode=tags)
recipients.contactIds	opt	Массив ID контактов (при mode=contacts)
throttle	opt	Задержка между отправками, мс (200-60000, по умолч. 1000)
tagOnSend	opt	Тег, присваиваемый контакту при отправке

Request
{
  "name": "Акция июнь",
  "channelId": "ch_abc",
  "message": {
    "type": "text",
    "text": "Скидка 20% только сегодня!"
  },
  "recipients": { "mode": "tags", "tags": ["VIP"] },
  "throttle": 1000,
  "tagOnSend": "акция-июнь"
}

PATCH /broadcasts/:id Обновить рассылку

🔒 Bearer токен · owner / admin

Обновляет draft-рассылку. Те же поля, что и при создании.

POST /broadcasts/:id/send Запустить отправку

🔒 Bearer токен · owner / admin

Запускает асинхронную отправку. Статус рассылки меняется на sending. Прогресс доступен через GET /broadcasts/:id/stats.

POST /broadcasts/:id/cancel Отменить отправку

🔒 Bearer токен · owner / admin

Останавливает активную рассылку. Статус → cancelled.

GET /broadcasts/:id/stats Статистика

🔒 Bearer токен

Response 200
{
  "total": 150,
  "sent": 120,
  "delivered": 115,
  "failed": 5
}

DELETE /broadcasts/:id Удалить рассылку

🔒 Bearer токен · owner / admin

Удаляет рассылку (только draft или completed). 204 No Content.

Автоответчики

Automations

GET /automations Список автоответчиков

🔒 Bearer токен

Возвращает все правила, отсортированные по приоритету (DESC).

POST /automations Создать правило

🔒 Bearer токен · owner / admin

Тело запроса

Поле	Тип	Описание
name	req	Название (1-200)
trigger.type	req	`keyword` \| `contains` \| `regex` \| `any`
trigger.value	opt	Значение триггера (до 500 символов)
actions	req	Массив действий (1-10)
actions[].type	req	`reply` \| `assign` \| `tag` \| `close`
actions[].text	opt	Текст ответа (для reply)
actions[].assignTo	opt	ID оператора (для assign)
actions[].tag	opt	Тег (для tag)
channelId	opt	Ограничить конкретным каналом
priority	opt	Приоритет 0-1000 (по умолч. 0)
oncePerContact	opt	Сработать не более 1 раза на контакт

Request
{
  "name": "Приветствие",
  "trigger": { "type": "any" },
  "actions": [
    { "type": "reply", "text": "Здравствуйте! Мы скоро ответим." }
  ],
  "priority": 10,
  "oncePerContact": true
}

PATCH /automations/:id Обновить правило

🔒 Bearer токен · owner / admin

Частичное обновление. Те же поля, что и при создании.

POST /automations/:id/toggle Вкл / Выкл

🔒 Bearer токен · owner / admin

Переключает isActive. Возвращает обновлённый объект.

DELETE /automations/:id Удалить

🔒 Bearer токен · owner / admin

204 No Content.

Каскады

Cascades

GET /cascades Список каскадов

🔒 Bearer токен

Возвращает все каскады аккаунта (без подробных sends).

POST /cascades Создать каскад

🔒 Bearer токен · owner / admin

Тело запроса

Поле	Тип	Описание
name	req	Название (1-200)
steps	req	Массив шагов (2-10)
steps[].channelId	req	ID канала для шага
steps[].timeout	opt	Таймаут в секундах (5-86400, по умолч. 300)

Request
{
  "name": "WA → Telegram",
  "steps": [
    { "channelId": "ch_wa", "timeout": 300 },
    { "channelId": "ch_tg", "timeout": 600 }
  ]
}

PATCH /cascades/:id Обновить каскад

🔒 Bearer токен · owner / admin

Частичное обновление. Те же поля, что и при создании.

POST /cascades/:id/send Отправить каскад

🔒 Bearer токен · owner / admin

Тело запроса

Поле	Тип	Описание
contactId	req	ID контакта-получателя
message	req	Объект: `{ type, text, media }`

Response 202
{ "ok": true, "sendId": "snd_abc" }

ℹ️

Каскад отправляет сообщение через первый канал. Если не доставлено за timeout — переходит к следующему шагу.

DELETE /cascades/:id Удалить каскад

🔒 Bearer токен · owner / admin

204 No Content.

Flow-builder

Flows

GET /flows Список flows

🔒 Bearer токен

Возвращает все flows, отсортированные по дате обновления.

POST /flows Создать flow

🔒 Bearer токен · owner / admin

Тело запроса

Поле	Тип	Описание
name	req	Название (1-200)
nodes	opt	Массив блоков: `{ id, type, position, data }`
nodes[].type	req	`trigger` \| `condition` \| `action` \| `delay`
nodes[].position	req	`{ x, y }` — позиция на canvas
edges	opt	Массив связей: `{ id, source, target, label? }`
isActive	opt	Активен ли (по умолч. false)

Request
{
  "name": "Приветственный flow",
  "nodes": [
    { "id": "n1", "type": "trigger", "position": {"x":100,"y":100} },
    { "id": "n2", "type": "action", "position": {"x":100,"y":250}, "data": {"text":"Привет!"} }
  ],
  "edges": [
    { "id": "e1", "source": "n1", "target": "n2" }
  ]
}

PATCH /flows/:id Обновить flow

🔒 Bearer токен · owner / admin

Сохраняет обновлённый граф (nodes + edges). Те же поля, что и при создании.

POST /flows/:id/toggle Вкл / Выкл

🔒 Bearer токен · owner / admin

Переключает isActive. Возвращает обновлённый объект.

DELETE /flows/:id Удалить flow

🔒 Bearer токен · owner / admin

204 No Content.

Вебхуки

Webhooks

GET /webhooks Список

🔒 Bearer токен

POST /webhooks Создать

🔒 Bearer токен

Поле	Тип	Описание
url	req	HTTPS URL приёмника
events	req	Массив событий: `["new_message","message_status"]`
secret	opt	Секрет для подписи HMAC-SHA256

POST /webhooks/:id/test Тестовый запрос

🔒 Bearer токен

Отправляет тестовое событие на Webhook и возвращает HTTP-код ответа.

DELETE /webhooks/:id Удалить

🔒 Bearer токен

204 No Content.

CRM-интеграции

CRM Integrations

Управление интеграциями с amoCRM, Bitrix24, YCLIENTS и comka.ru (тип comkacrm). Креденшиалы хранятся в зашифрованном виде.

GET /crm Список CRM-интеграций

Возвращает все настроенные CRM-интеграции аккаунта. Поля credentials замаскированы (****).

Response 200
[{
  "id": "abc123",
  "type": "amocrm",
  "isActive": true,
  "credentials": { "domain": "company.amocrm.ru", "clientId": "****" }
}]

POST /crm Создать интеграцию

Параметр	Тип	Описание
type	string	`amocrm` \| `bitrix24` \| `yclients` \| `comkacrm` required
credentials	object	Объект с учётными данными (зависит от типа) required

Credentials по типам:

amoCRM: domain, clientId, clientSecret, authCode

Bitrix24: webhookUrl или domain + clientId + clientSecret + authCode

YCLIENTS: обычно подключается через Marketplace. Для API-подключения достаточно companyId (токены берутся из server config при необходимости).

comka.ru: см. раздел comkacrm в панели интеграций (embed + webhooks + auto-create lead).

Request
{
  "type": "bitrix24",
  "credentials": {
    "webhookUrl": "https://company.bitrix24.ru/rest/1/abc123/"
  }
}

PATCH /crm/:id Обновить интеграцию

Обновляет credentials и/или isActive. Новые credentials мержатся с существующими.

Request
{
  "isActive": false
}

POST /crm/:id/test Проверить подключение

Делает тестовый запрос к CRM API. Возвращает {"ok": true} или ошибку.

DELETE /crm/:id Удалить интеграцию

Удаляет интеграцию. Синхронизация прекращается немедленно.

POST /crm/yclients/connect Marketplace-подключение YCLIENTS

Создаёт YCLIENTS-интеграцию из маркетплейс-события. Используется при установке приложения из YCLIENTS.

Параметр	Тип	Описание
salonId	string	ID филиала в YCLIENTS required
salonName	string	Название филиала opt
userData	string	Base64 payload из Marketplace opt
userDataSign	string	HMAC подпись payload opt

POST /crm/:id/yclients/import-templates Импорт шаблонов уведомлений YCLIENTS

Импортирует пресеты шаблонов YCLIENTS (новая запись, подтверждение, перенос, отмена, напоминание, отзыв, день рождения).

Ответ 200

{ "ok": true, "imported": 7 }

Real-time

WebSocket Events

⚡

Подключитесь по URL: wss://panel.wonderchat.ru?token=<jwt>. События приходят в формате {"type":"event_name","data":{...}}.

`new_message`

Новое входящее или исходящее сообщение.

{ "type": "new_message", "data": { "id": "msg1", "conversationId": "c1", "direction": "in", "type": "text", "text": "Привет!" } }

`message_status`

Ютатус сообщения изменился: sent → delivered → read.

{ "type": "message_status", "data": { "id": "msg1", "status": "read" } }

`channel_status`

Ютатус канала изменился: online | offline | connecting.

{ "type": "channel_status", "data": { "channelId": "ch1", "status": "online" } }

`qr_code`

Новый QR-код сгенерирован для WhatsApp.

{ "type": "qr_code", "data": { "channelId": "ch1", "qr": "data:image/png;base64,..." } }

`typing`

Пользователь пишет в выбранном диалоге.

{ "type": "typing", "data": { "conversationId": "c1" } }