Если запрос к Rocket.Chat API возвращает 401 Unauthorized или пустой ответ, чаще всего причина в отсутствующих заголовках X-Auth-Token и X-User-Id — без них сервер отклоняет любые обращения к защищённым эндпоинтам. Проверка этой пары заголовков — первое действие при любой проблеме с интеграцией.
Rocket.Chat предоставляет несколько программных интерфейсов: REST API для управления пользователями, каналами и сообщениями, Realtime API на базе WebSocket для мгновенных событий, а также Incoming и Outgoing Webhooks для простых интеграций без полноценного клиента. В этой статье разберём, как получить доступ, какие методы использовать и как избежать типичных ошибок при подключении.
Способы авторизации в Rocket.Chat API
Для работы с REST API требуется получить пару значений: токен авторизации и идентификатор пользователя. Классический способ — POST-запрос к эндпоинту /api/v1/login с логином и паролем в теле запроса. В ответе сервер вернёт объект с полями authToken и userId, которые затем передаются в заголовках каждого запроса.
curl -X POST https://chat.example.com/api/v1/login \
-H "Content-Type: application/json" \
-d '{"user": "bot", "password": "secret"}'
Альтернативный вариант — персональные токены доступа (Personal Access Tokens). Их создают в профиле пользователя, если администратор включил эту возможность в настройках сервера. Такой токен не требует передачи пароля и удобен для скриптов и ботов, работающих постоянно.
- 🔑 Токен от
/api/v1/loginпривязан к сессии и может стать недействительным после выхода из всех сессий - 🧩 Персональный токен создаётся в разделе профиля пользователя и действует до ручного отзыва
- 🛡️ Для ботов заводите отдельную учётную запись с минимально необходимыми правами
- 🔄 При получении 401 первым делом проверьте срок жизни токена и корректность заголовков
⚠️ Внимание: токен даёт полный доступ от имени пользователя. Никогда не публикуйте его в репозиториях, логах и клиентском коде — храните в переменных окружения или менеджере секретов.
Основные REST-эндпоинты
Структура REST API построена вокруг сущностей: пользователи, каналы, группы, сообщения. Базовый префикс всех вызовов — /api/v1/. Ниже приведены наиболее востребованные методы; полный актуальный список всегда стоит сверять с официальной документацией вашей версии сервера, так как набор эндпоинтов меняется между релизами.
| Эндпоинт | Метод | Назначение |
|---|---|---|
/api/v1/chat.postMessage | POST | Отправка сообщения в канал или личку |
/api/v1/channels.list | GET | Список публичных каналов |
/api/v1/users.create | POST | Создание пользователя (нужны права администратора) |
/api/v1/channels.history | GET | История сообщений канала |
/api/v1/me | GET | Информация о текущем пользователе |
Отправка сообщения — самая частая операция. Запрос к chat.postMessage принимает идентификатор комнаты (roomId) и текст. Вместо roomId можно указать канал через поле channel с символом #. В теле также поддерживаются вложения, упоминания и кастомные поля.
curl -X POST https://chat.example.com/api/v1/chat.postMessage \
-H "X-Auth-Token: TOKEN" \
-H "X-User-Id: USER_ID" \
-H "Content-Type: application/json" \
-d '{"channel": "#general", "text": "Привет из API!"}'
Вебхуки: простая интеграция без клиента
Если задача — только отправлять уведомления в канал (алерты из мониторинга, события CI/CD), полноценный API-клиент не нужен. Достаточно Incoming Webhook: администратор создаёт его в разделе администрирования Integrations, получает уникальный URL, и любой сервис может слать на него POST-запросы с JSON.
Формат тела webhook-запроса совместим с простыми полями: text, username, icon_emoji, attachments. Это позволяет перенаправлять уведомления из систем, которые изначально рассчитаны на формат Slack, с минимальными правками.
- 📥 Incoming Webhook — приём сообщений в Rocket.Chat из внешних систем
- 📤 Outgoing Webhook — отправка событий из Rocket.Chat наружу при триггерах (сообщение в канале, упоминание)
- ⚙️ В настройках интеграции можно включить выполнение скрипта для обработки входящих данных
- 🔐 URL вебхука содержит секрет — его утечка равнозначна утечке права на отправку сообщений
Realtime API и события в реальном времени
Для ботов, которым нужно мгновенно реагировать на новые сообщения, REST-опрос не подходит — используется Realtime API. Он работает поверх WebSocket с протоколом DDP (Distributed Data Protocol), тем же, что лежит в основе самого клиента Rocket.Chat. Подключение устанавливается к адресу wss://your-server/websocket.
После соединения клиент отправляет сообщение connect, затем авторизуется методом login с токеном и подписывается на поток событий комнаты. Подписка stream-room-messages доставляет новые сообщения конкретной комнаты в реальном времени. Для большинства языков существуют готовые SDK, которые скрывают детали протокола DDP.
⚠️ Внимание: при работе через WebSocket за reverse-proxy (Nginx, Apache) убедитесь, что прокси корректно проксирует Upgrade-заголовки. Ошибка handshake на этапе подключения — типичный признак неправильно настроенного проксирования WebSocket.
Что такое DDP и зачем он нужен
DDP (Distributed Data Protocol) — протокол, изначально созданный для Meteor. Он передаёт данные в формате JSON и поддерживает вызовы методов и подписки на изменения данных. Rocket.Chat использует его для синхронизации состояния между сервером и клиентами, поэтому Realtime API наследует эту модель.
Пошаговая настройка первой интеграции
Разберём практический сценарий: бот, который читает сообщения канала и отвечает на команды. Порядок действий одинаков для большинства подобных задач, независимо от языка программирования.
☑️ Подготовка бота для Rocket.Chat
После создания пользователя важно проверить права: роль bot ограничивает некоторые действия, и если боту нужно, например, создавать каналы, потребуются дополнительные разрешения. Проверка выполняется простым запросом к /api/v1/me — в ответе видны роли и идентификатор учётной записи.
На этапе отладки удобно логировать полные ответы сервера. Поле error в теле ответа при success: false содержит машиночитаемый код причины отказа — по нему проще всего понять, чего не хватает: прав, параметра или корректного roomId.
Типичные ошибки и их диагностика
Большинство проблем при работе с Rocket.Chat API сводится к нескольким повторяющимся сценариям. Ниже — те, что встречаются чаще всего.
- 🚫
401 Unauthorized— неверный или просроченный токен, отсутствуют заголовки авторизации - 🔍
error-room-not-found— канал не существует или у пользователя нет к нему доступа - ⏳ Ограничение частоты запросов (rate limiting) — сервер отклоняет слишком частые обращения; добавьте задержки и обработку повторов
- 🌐 Таймауты через прокси — проверьте настройки WebSocket и таймауты на уровне Nginx
- 🧾
400 Bad Request— ошибка в структуре JSON или отсутствует обязательное поле
Если запрос возвращает HTML-страницу вместо JSON, почти наверняка нарушен путь: либо неверный домен, либо прокси перенаправляет запрос на веб-интерфейс. Проверьте, что обращение идёт именно к /api/v1/..., а ответ имеет заголовок Content-Type: application/json.
Ограничения и безопасность
Набор доступных методов и поведение API зависят от версии сервера Rocket.Chat — эндпоинты переименовываются, появляются новые параметры, устаревшие методы помечаются как deprecated. Перед разработкой интеграции сверьтесь с документацией именно вашей версии: она доступна в разделе администрирования и в официальном developer-справочнике проекта.
Для production-интеграций важно продумать отказоустойчивость: повторные попытки при сетевых ошибках, обновление токена при 401, очередь сообщений при временной недоступности сервера. Также учитывайте, что массовые операции (создание тысяч пользователей, рассылки) лучше выполнять порциями, чтобы не перегружать сервер.
⚠️ Внимание: не используйте учётную запись администратора для рутинных интеграций. Компрометация токена с полными правами даёт злоумышленнику контроль над всем сервером, включая чтение приватных переписок.
Часто задаваемые вопросы
Как получить roomId канала для отправки сообщения?
Идентификатор комнаты можно получить запросом к /api/v1/channels.info?roomName=имя или из ответа /api/v1/channels.list. Также вместо roomId во многих методах допустимо передавать channel с символом # перед именем.
Чем Realtime API отличается от REST API?
REST API работает по модели «запрос — ответ» и подходит для разовых операций: отправить сообщение, создать пользователя. Realtime API держит постоянное WebSocket-соединение и позволяет получать события (новые сообщения, изменения) мгновенно, без опроса сервера.
Токен перестал работать, хотя ничего не менялось. Почему?
Возможные причины: сессия была завершена (выход из всех сессий в настройках), токен отозван администратором, изменён пароль пользователя. Получите новый токен через /api/v1/login и проверьте, не сбрасывались ли сессии на сервере.
Можно ли использовать вебхуки Slack с Rocket.Chat?
Формат сообщений Incoming Webhook в Rocket.Chat во многом совместим со Slack-форматом: поля text, attachments, username поддерживаются. Однако не все расширенные возможности (например, часть интерактивных элементов) переносятся один в один — сложные вложения стоит проверить на тестовом канале.
Есть ли официальные SDK для Rocket.Chat API?
Сообщество и команда Rocket.Chat поддерживают клиентские библиотеки для нескольких языков, включая JavaScript/TypeScript и Python. Актуальный список SDK и их статус лучше проверять в официальном репозитории проекта, так как поддержка отдельных библиотек со временем меняется.