REST: imbot.message.add (боты)

Метод imbot.message.add отправляет сообщение в чат от имени зарегистрированного чат-бота Битрикс24. В отличие от im.message.add, который пишет от лица пользователя, бот работает автономно, реагирует на события и использует интерактивные клавиатуры. Разберём регистрацию бота, отправку и оформление сообщений.

Регистрация бота: imbot.register

Прежде чем бот сможет писать, его нужно зарегистрировать методом imbot.register. Он доступен только приложениям с правами imbot — простой входящий вебхук здесь не подойдёт, нужен контекст локального или тиражного приложения.

Ключевые параметры регистрации:

• CODE — внутренний код бота (уникален в рамках приложения);
• TYPE — B (обычный бот) или O (бот-оператор Открытых линий);
• EVENT_MESSAGE_ADD, EVENT_WELCOME_MESSAGE, EVENT_BOT_DELETE — URL обработчиков событий;
• PROPERTIES — имя, аватар, должность бота.

Метод возвращает BOT_ID — его понадобится подставлять в дальнейшие вызовы. Удаляется бот методом imbot.unregister.

Отправка сообщения

Основной рабочий метод — imbot.message.add. Обязательны идентификатор диалога и текст.

POST https://portal.bitrix24.ru/rest/imbot.message.add.json

{ "BOT_ID": 55, "DIALOG_ID": "chat120", "MESSAGE": "Заявка №[B]345[/B] принята в работу" }

Параметр DIALOG_ID адресует получателя: для личного диалога это ID пользователя (число), для группового чата — строка вида chat120. Текст поддерживает BB-коды: [B], [I], [URL=…], [USER=…], перенос строки — обычный \n.

Метод возвращает ID отправленного сообщения, который пригодится для последующего редактирования или удаления.

Интерактивные клавиатуры

Главное преимущество ботов — кнопки под сообщением. Клавиатура передаётся в параметре KEYBOARD как массив кнопок.

"KEYBOARD": [ { "TEXT": "Подтвердить", "COMMAND": "confirm", "COMMAND_PARAMS": "345", "BG_COLOR": "#29619b", "TEXT_COLOR": "#fff" }, { "TEXT": "Открыть заявку", "LINK": "https://portal.bitrix24.ru/..." } ]

Кнопки бывают двух типов:

Параметр DISPLAY: "LINE" располагает кнопки в строку, BLOCK — блоком. Клавиатуру можно менять, редактируя сообщение через imbot.message.update.

Вложения и форматирование

Для структурированных карточек используется параметр ATTACH — набор блоков с заголовками, полями, ссылками и картинками.

• MESSAGE — текстовый блок внутри вложения;
• GRID — сетка «поле: значение»;
• IMAGE — изображение по URL;
• LINK — кликабельная ссылка;
• DELIMITER — разделитель;
• COLOR — цветная полоса слева от блока.

Вложения удобны для уведомлений о сделках или заявках: в компактной карточке видны сумма, ответственный и статус. При этом основной MESSAGE можно оставить кратким или пустым, если вся информация в attach.

Команды и служебные методы

Бот может реагировать на команды вида /help. Они регистрируются методом imbot.command.register с параметрами COMMAND, COMMON (доступна во всех чатах) и EVENT_COMMAND_ADD — URL обработчика.

Другие полезные методы группы:

1. imbot.message.update — изменить текст или клавиатуру отправленного сообщения;
2. imbot.message.delete — удалить сообщение;
3. imbot.chat.sendTyping — показать индикатор «печатает»;
4. imbot.chat.add — создать групповой чат с ботом;
5. imbot.chat.user.add — добавить участников в чат.

Отличие от im.message.add

Начинающие путают два метода. Ключевая разница — от чьего имени и с какими возможностями отправляется сообщение.

Если нужны кнопки, автономные ответы и сценарии диалога — это территория ботов. Для простой отправки уведомления от лица сотрудника достаточно im.message.add или im.notify.system.add.

Итог

Чат-бот Битрикс24 строится вокруг imbot.register и imbot.message.add: регистрация с обработчиками событий, отправка сообщений с BB-кодами, интерактивные клавиатуры, карточки-вложения и команды. Важно помнить о правах приложения и быстром ответе обработчиков, вынося тяжёлую логику в очередь.

Мы разрабатываем чат-ботов Битрикс24 под конкретные процессы: согласования, уведомления по сделкам, опросы и подключение к внешним сервисам. Спроектируем сценарии диалога, устойчивую обработку событий и интеграцию с вашими системами.