Семейство im.* — REST-интерфейс встроенного мессенджера Битрикс24. Через него приложение шлёт сообщения в личные и групповые чаты, создаёт беседы, редактирует и удаляет посты, добавляет вложения и интерактивные клавиатуры.
Мессенджер через REST: скоуп im
Методы работы с чатом входят в скоуп im. Отправка сообщения от лица пользователя выполняется методом im.message.add. Ключевой параметр — DIALOG_ID, который определяет адресата.
imbot.message.add. Метод im.message.add шлёт от имени пользователя, чьим токеном выполнен запрос.Что такое DIALOG_ID
Адресат кодируется в DIALOG_ID по простым правилам:
| Формат | Кому уйдёт |
|---|---|
17 (число) | личный диалог с пользователем ID 17 |
chat240 | групповой чат с внутренним ID 240 |
sg15 | чат рабочей группы (socialnetwork group) 15 |
Личный чат с пользователем не требует предварительного создания — достаточно указать его ID. Для группового нужен идентификатор существующего чата, полученный при создании или из im.recent.get.
Отправка сообщения
Минимальный вызов содержит адресата и текст:
POST /rest/1/xxxx/im.message.add.json
{"DIALOG_ID":"chat240","MESSAGE":"Заявка №5012 переведена в работу"}
Текст поддерживает BB-код: [B]жирный[/B], [URL=...]ссылка[/URL], перенос строки, эмодзи, упоминание [USER=17] [/USER]. В ответе возвращается ID созданного сообщения — сохраните его, если планируете правку или удаление.
Дополнительные параметры:
SYSTEM=Y— системное (серое) сообщение без автора;ATTACH— структурированное вложение (карточка);KEYBOARD— набор кнопок под сообщением;URL_PREVIEW=Y|N— включить или отключить превью ссылок.
Вложения и клавиатуры
Параметр ATTACH — это массив блоков: заголовок, поля, картинка, ссылка. Он рисует аккуратную карточку вместо простого текста. KEYBOARD добавляет интерактивные кнопки:
{"DIALOG_ID":"17","MESSAGE":"Подтвердить заявку?","KEYBOARD":[{"TEXT":"Да","COMMAND":"approve","COMMAND_PARAMS":"5012","BG_COLOR":"#29619b"},{"TEXT":"Нет","COMMAND":"reject","COMMAND_PARAMS":"5012"}]}
COMMAND полноценно обрабатываются только ботами: нажатие рождает командное событие у зарегистрированного чат-бота. Для простых ссылок используйте кнопку с параметром LINK.Создание чатов и участники
Групповые беседы управляются отдельными методами:
im.chat.add— создать чат (TYPE, TITLE, DESCRIPTION, COLOR, USERS[]); возвращает CHAT_ID;im.chat.user.add/im.chat.user.list— добавить и перечислить участников;im.chat.updateTitle,im.chat.updateColor— свойства чата;im.chat.setOwner,im.chat.leave— владелец и выход.
Полученный CHAT_ID превращается в DIALOG_ID добавлением префикса chat. Для чтения ленты и отметки прочтения есть im.dialog.get и im.dialog.read, а список последних диалогов даёт im.recent.get.
Редактирование, удаление и реакции
После отправки сообщение можно менять:
| Метод | Действие |
|---|---|
im.message.update | изменить текст (MESSAGE_ID, MESSAGE) |
im.message.delete | удалить (MESSAGE_ID) |
im.message.like | поставить/снять лайк |
MESSAGE_ID из ответа im.message.add — без него отредактировать пост не получится.Итог
Семейство im.* превращает мессенджер Битрикс24 в канал доставки уведомлений и интерактива. Главное — правильно собрать DIALOG_ID, сохранять MESSAGE_ID для правок и помнить, что кнопки-команды раскрываются только вместе с чат-ботом.
Мы связываем чаты Битрикс24 с внешними системами: заявки, статусы заказов, алерты мониторинга приходят прямо в нужный диалог, а кнопки запускают сценарии. Проектируем такие интеграции и сопровождаем их после запуска.
Частые вопросы
Как отправить личное сообщение пользователю?
Передайте в DIALOG_ID числовой ID сотрудника, например 17, и текст в MESSAGE. Предварительно создавать диалог не нужно.
Чем im.message.add отличается от imbot.message.add?
im.message.add шлёт от имени пользователя вызова, imbot.message.add — от имени зарегистрированного чат-бота с его аватаром и именем. Для интерактивных ботов используют второй вариант.
Как отправить сообщение в групповой чат?
Используйте DIALOG_ID вида chatID, например chat240, где 240 — внутренний идентификатор чата, полученный при создании через im.chat.add.
Поддерживается ли форматирование текста?
Да, MESSAGE понимает BB-код: жирный, курсив, ссылки, упоминания USER, переносы строк и эмодзи. HTML в сообщениях не используется.
Как сделать сообщение без автора?
Передайте параметр SYSTEM=Y — сообщение отобразится как системное, серым текстом, без привязки к конкретному пользователю.
Почему не срабатывают кнопки клавиатуры?
Кнопки с COMMAND обрабатывает чат-бот через свои события. Без зарегистрированного бота работают только кнопки-ссылки с параметром LINK.
Можно ли отредактировать чужое сообщение?
Как правило нет — правка и удаление доступны для собственных сообщений. Поэтому важно сохранять MESSAGE_ID из ответа при отправке.
Как получить ID чата рабочей группы?
Для чата группы используйте формат sgID (например sg15) или найдите CHAT_ID через im.recent.get. Соцсетевые группы адресуются префиксом sg.
Поможем с настройкой и поддержкой Для разработчиков
Поможем с настройкой, доработкой и поддержкой Для разработчиков.