Чат-боты и коннекторы — два способа расширить мессенджер Битрикс24 через REST. Боты (imbot.*) живут внутри портала и общаются с сотрудниками, коннекторы (imconnector.*) приводят в открытые линии внешние каналы: свой мессенджер, соцсеть, чат сайта.
Бот и коннектор: в чём разница
Оба механизма строятся на событийной модели REST, но решают разные задачи.
| Чат-бот (imbot) | Коннектор (imconnector) | |
|---|---|---|
| Где работает | внутренние чаты портала | открытые линии, внешние каналы |
| Собеседник | сотрудник компании | внешний клиент |
| Скоуп | imbot | imopenlines, imconnector |
| Типовой сценарий | помощник, авто-ответы, команды | подключить свой чат к оператору |
Регистрация чат-бота
Бот создаётся методом imbot.register. В параметрах указывают код, имя, аватар и, главное, адреса обработчиков событий:
POST /rest/imbot.register.json?auth=TOKEN
{"CODE":"helper","TYPE":"B","EVENT_MESSAGE_ADD":"https://app.example.com/bot/onMessage","EVENT_WELCOME_MESSAGE":"https://app.example.com/bot/onWelcome","PROPERTIES":{"NAME":"Помощник","COLOR":"AZURE"}}
События и ответы бота
Логика бота — это реакция на события, которые портал шлёт на ваши URL:
ONIMBOTMESSAGEADD— пользователь написал боту; отвечаем черезimbot.message.add;ONIMBOTJOINCHAT— бота добавили в чат;ONIMCOMMANDADD— вызвана команда бота (например/help), отвечаем черезimbot.command.answer;ONIMBOTDELETE— бот удалён.
Команды регистрируются заранее методом imbot.command.register. Ответы бота идут через его семейство: imbot.message.add, imbot.message.update, imbot.message.delete. Сообщения бота могут нести те же ATTACH и KEYBOARD, что и обычные, но именно у бота кнопки-команды работают в полную силу.
Коннектор открытых линий
Коннектор регистрируется методом imconnector.register и затем активируется для конкретной открытой линии через imconnector.activate. После этого настраивается визитка канала:
imconnector.register— объявить коннектор (ID, NAME, ICON);imconnector.activate— включить для линии (CONNECTOR, LINE, ACTIVE);imconnector.connector.data.set— данные подключённого аккаунта канала;imconnector.status— проверить состояние подключения.
Скоуп imopenlines/imconnector обязателен. Коннектор — это тоже приложение: без обработчиков входящих событий двусторонний обмен невозможен.
Поток сообщений коннектора
Обмен идёт в обе стороны:
- Клиент пишет во внешнем канале → ваше приложение принимает сообщение и передаёт в Битрикс24 методом
imconnector.send.messages; - Оператор отвечает в открытой линии → портал шлёт событие
ONIMCONNECTORMESSAGEADDна ваш обработчик; - Приложение доставляет ответ обратно во внешний канал по его API.
Статусы доставки и прочтения возвращают методы imconnector.send.status.delivery и imconnector.send.status.reading — благодаря им оператор видит «доставлено/прочитано», как в привычных мессенджерах.
Итог
Боты (imbot.*) автоматизируют внутренние чаты и команды, коннекторы (imconnector.*) заводят внешние каналы в открытые линии. Оба механизма событийные и требуют полноценного приложения с обработчиками — простого вебхука недостаточно.
Мы разрабатываем и ботов-помощников, и коннекторы под конкретные мессенджеры и каналы: от регистрации и обработки событий до доставки статусов и отказоустойчивости. Поможем спроектировать архитектуру и запустить интеграцию в бой.
Частые вопросы
Можно ли создать бота через входящий вебхук?
Нет. Бот реагирует на события, которые Битрикс24 шлёт на ваши URL, поэтому нужно локальное или тиражное приложение с исходящими обработчиками, а не простой вебхук.
В чём разница между ботом и коннектором?
Бот работает во внутренних чатах и общается с сотрудниками. Коннектор подключает внешний канал (мессенджер, чат сайта) к открытым линиям, где с клиентом общается оператор.
Как бот отвечает на сообщение?
На событие ONIMBOTMESSAGEADD приложение вызывает imbot.message.add с DIALOG_ID из события и текстом ответа. Так формируется диалог с ботом.
Как зарегистрировать команду бота вроде /help?
Методом imbot.command.register задаётся команда, а на её вызов приходит событие ONIMCOMMANDADD; ответ отправляется через imbot.command.answer.
Какой скоуп нужен для коннектора?
Открытые линии и коннекторы требуют скоупов imopenlines и imconnector. Без них методы imconnector.* и активация линии недоступны.
Как передать сообщение клиента в открытую линию?
Ваше приложение принимает сообщение из внешнего канала и вызывает imconnector.send.messages, указывая коннектор, линию и данные чата и пользователя.
Как оператор узнаёт, что клиент прочитал ответ?
Коннектор передаёт статусы методами imconnector.send.status.delivery и imconnector.send.status.reading, и оператор видит отметки доставки и прочтения.
Когда выбрать коннектор, а не готовую интеграцию?
Когда нужного канала нет в Маркетплейсе: собственный чат на сайте, кастомный мессенджер, мобильное приложение. Коннектор даёт универсальный двусторонний обмен с открытыми линиями.
Поможем с настройкой и поддержкой Для разработчиков
Поможем с настройкой, доработкой и поддержкой Для разработчиков.