Чат и события WebSocket
Диалоги, сообщения, доступ профиля и восстановление после разрыва соединения
Доступ и адреса
Все адреса относятся к вашей CMS, например https://cms.example.com. REST-диалоги зарегистрированы под /api/v1/conversations, WebSocket — /api/v1/ws. В старых Swagger-аннотациях встречается /chat/conversations; для перечисленных ниже операций используйте зарегистрированные пути.
Нужны авторизация в CMS и разрешение профиля messages.manage. При работе от имени команды сервер повторно проверяет действующего участника и разрешение при действиях WebSocket. Доступ к справочнику по лицензии платформы не заменяет эти права.
REST: начать диалог и прочитать историю
| Операция | Результат |
|---|---|
GET /api/v1/conversations/ | Список: items, total, page, per_page, total_pages |
POST /api/v1/conversations/ | Созданный или найденный диалог, HTTP 201 |
GET /api/v1/conversations/{id} | Доступный текущему профилю диалог |
GET /api/v1/conversations/{id}/messages | Страница сообщений в таком же контейнере |
POST /api/v1/conversations/{id}/messages | Сохранённое сообщение, HTTP 201; действует rate limit |
PUT /api/v1/conversations/{id}/read | Отметка прочтения |
PUT /api/v1/conversations/{id}/unread | Отметка непрочитанного диалога |
Создание принимает user_id другого пользователя и необязательный listing_id:
{"user_id":"<user UUID>","listing_id":"<listing UUID>"}Для списка диалогов page начинается с 1; per_page по умолчанию 20, допустимо 1–100. Для истории значение по умолчанию 50, диапазон 1–100. Недоступный или отсутствующий диалог возвращает 404.
Текстовое сообщение через REST:
{"text":"Здравствуйте","message_type":"text"}REST поддерживает text, voice, file, image, video, location. Для медиа нужен file_url; также есть file_name, file_size, duration. Текст проверяется по длине в байтах, максимум 5000; пустое текстовое сообщение не принимается. Ошибка тела или типа сообщения — 400. Файлы сначала загружаются штатным механизмом CMS с его проверками доступа.
WebSocket
Браузер подключается после обычного входа в CMS:
const socket = new WebSocket('wss://cms.example.com/api/v1/ws');
socket.onmessage = ({ data }) => {
const event = JSON.parse(data);
// Обновите интерфейс по event.type, затем сверяйте состояние через REST.
};Handshake принимает только access-cookie CMS. Bearer-заголовок и токен в URL не заменяют cookie. Без неё сервер возвращает 401. Origin должен соответствовать хосту CMS или настроенному списку разрешённых origins. Для клиента вне браузера согласуйте обычный cookie-based вход и настройку Origin вашей установки.
Входящие JSON-события:
type | Поля | Назначение |
|---|---|---|
send_message | conversation_id, непустой text | Текстовое сообщение |
mark_read | conversation_id | Отметка прочтения |
typing | conversation_id | Индикатор набора, если включён настройкой CMS |
{"type":"send_message","conversation_id":"<conversation UUID>","text":"Здравствуйте"}Исходящие события:
type | Поля |
|---|---|
new_message | message: сохранённое сообщение с id, conversation_id, sender_id, text, message_type, created_at и другими полями |
messages_read | conversation_id, reader_id |
typing | conversation_id, user_id |
new_notification | notification: пользовательское уведомление |
new_admin_notification | notification: административное уведомление для назначенного получателя |
Предел входящего WebSocket-сообщения — 4096 байт всего JSON, меньше REST-предела текста. Сервер отправляет ping каждые 54 секунды и ждёт pong в пределах 60 секунд; стандартный браузер автоматически отвечает pong на входящий ping. Срок записи — 10 секунд. Для больших текстов и медиа используйте REST.
Повторное подключение и ошибки
Протокол не содержит request ID, ack ошибки, курсор воспроизведения или ключ идемпотентности. Неизвестные события, неверный JSON и ряд отказов действия не получают отдельного ответа. Отсутствие ошибки в сокете не доказывает сохранение сообщения. Подтверждением служат new_message с ID и повторное чтение истории.
После разрыва заново подключитесь и перечитайте диалоги, историю открытого диалога и непрочитанные уведомления; объединяйте сообщения по id. Не повторяйте автоматически отправку с неизвестным результатом: можно создать дубль. Штатный веб-клиент CMS использует задержки 3, 6, 12, 24, затем 30 секунд; закрытия 1008, 4401, 4403 останавливают автоматические попытки.
Уведомления читаются через GET /api/v1/notifications/ и GET /api/v1/notifications/unread-count. Эти REST-маршруты требуют владельца профиля. Доставка события WebSocket не доказывает доставку email, push, Telegram или внешнего канала: они имеют отдельные настройки и результат.
На тестовой установке проверьте два разных профиля, запрет доступа к чужому диалогу, отозванное разрешение команды и восстановление истории после отключения. Состояние сообщения и оплаты заказа — отдельные контракты.