Чат-бот для Битрикс24: разработка на Bot API от идеи до продакшена

Чат-бот в корпоративном мессенджере Битрикс24 — это не «игрушка с кнопочками», а полноценный интерфейс к CRM и бизнес-процессам. Сотрудники общаются с порталом там же, где обсуждают рабочие вопросы: ставят задачи, запрашивают отпуск, узнают статус сделки, регистрируют заявки. В этой статье разберём, как построить бота на локальном Bot API коробочной версии и Bitrix24 REST API — от регистрации до продакшен-эксплуатации.

Тема особенно актуальна для коробки: локальный Bot API работает внутри периметра компании, не зависит от внешних сервисов и позволяет обрабатывать чувствительные данные без выхода в интернет. Именно так мы строим чат-ботов в большинстве наших проектов по внедрению коробочного Битрикс24.

Содержание

• Как устроен чат-бот Битрикс24
• Регистрация бота и приём событий
• Архитектура обработчика команд
• Интеграция с CRM: бот, который создаёт сделки
• Три рабочих сценария из практики
• Типичные ошибки и как их избежать
• Чек-лист перед запуском в продакшен
• Вывод
• FAQ

Как устроен чат-бот Битрикс24

Бот в Битрикс24 — это не standalone-приложение, а связка из трёх частей:

• Чат-бот в ядре портала — зарегистрированный через чат-бот API обработчик, который получает входящие сообщения и команды (слэш-команды вида /start, /lead).
• Обработчик на внешнем сервере (для коробки — на локальном Bot API или REST-обработчике) — ваш код, который принимает события и отвечает через REST.
• REST API — канал общения: отправка сообщений, клавиатур, файлов, обращения к CRM, задачам, бизнес-процессам.

Боты бывают открытые (доступны всем сотрудникам, это основной тип для HR и заявок), скрытые (только по приглашению, удобны для админских функций) и сетевые (для Открытых линий и внешних каналов). Для внутренних сценариев берём открытый бот с ограничением по подразделениям.

Ключевой принцип: бот — это тонкий клиент к порталу. Вся бизнес-логика живёт в вашем обработчике, а портал остаётся единственным источником данных.

Регистрация бота и приём событий

Регистрация через REST

Регистрируем бота методом imbot.register (для облака) или локальным Bot API на коробке. Указываем код обработчика, URL, имя и возможности бота:

POST /rest/imbot.register
{
  "CODE": "request_bot",
  "TYPE": "O",
  "EVENT_MESSAGE_ADD": "https://bot.example.ru/handler.php",
  "EVENT_WELCOME_MESSAGE": "https://bot.example.ru/handler.php",
  "PROPERTIES": {
    "NAME": "Заявки",
    "WORK_POSITION": "Помощник по заявкам"
  },
  "AUTH": {
    "DOMAIN": "portal.example.ru",
    "TOKEN": "..."
  }
}

События, на которые стоит подписаться

• ONIMBOTMESSAGEADD — входящее сообщение боту (основная точка входа).
• ONIMBOTJOINCHAT — бота добавили в чат (отправляем приветствие с меню).
• ONIMCOMMANDADD — слэш-команда из любого чата.

При регистрации Bot API вернёт BOT_ID и TOKEN — сохраните их в защищённом хранилище, они пригодятся для исходящих вызовов. Для коробки все вызовы идут внутри локальной сети, что упрощает требования ИБ и обходится без публичных вебхуков.

Архитектура обработчика команд

Почему не один файл-обработчик

Главная ошибка новичков — один монолитный handler.php на все случаи. На третьей команде такой файл становится неподдерживаемым. Правильная структура — роутинг по типу события и команде:

// Общий обработчик событий
$event = $_REQUEST['event'] ?? '';
$botId = $_REQUEST['data']['BOT_ID'] ?? 0;

switch ($event) {
    case 'ONIMBOTMESSAGEADD':
        $handler = new MessageHandler($botId, $_REQUEST['data']);
        $handler->dispatch(); // роутинг по команде
        break;
    case 'ONIMBOTJOINCHAT':
        MessageHelper::sendWelcome($botId, $_REQUEST['data']['DIALOG_ID']);
        break;
}

Практические требования, которые мы закладываем в каждый проект:

• Идемпотентность — событие может прийти дважды; обработку ведём через уникальный ключ сообщения.
• Очередь — тяжёлые операции (генерация документа, выгрузка в 1С) отправляем в очередь и сразу отвечаем «принято, пришлю результат».
• Логирование — каждый входящий payload и исходящий вызов REST пишем с метками, иначе в проде не отладите ничего.
• Rate limit на пользователя — защита от «спама кнопками», которая душит и портал, и CRM.

Клавиатуры формируем встроенным форматом кнопок и меню команд — это нативный UX Битрикс24, который сотрудник уже знает по мобильному приложению.

Интеграция с CRM: бот, который создаёт сделки

Самый востребованный сценарий: сотрудник пишет боту «клиент Иван, +7..., интересуется внедрением» — и в CRM появляется лид со всеми полями. Разберём на примере создания лида:

POST /rest/crm.lead.add
{
  "fields": {
    "TITLE": "Заявка из чата: Иван Петров",
    "NAME": "Иван",
    "LAST_NAME": "Петров",
    "PHONE": [{"VALUE": "+7 900 123-45-67", "VALUE_TYPE": "WORK"}],
    "SOURCE_DESCRIPTION": "Чат-бот «Заявки»",
    "UF_CRM_LEAD_COMMENT": "интересуется внедрением коробки"
  }
}

Три правила из практики:

1. Дедупликация по телефону/email через crm.duplicate.findbycomm — иначе за месяц получите «Иван Петров (14)».
2. Источник и ответственного фиксируем явно, чтобы роботы CRM и сквозная аналитика работали корректно.
3. Ответ бота должен содержать ссылку на созданную карточку — мелочь, которая убирает половину вопросов «а куда это улетело».

Для сложных интеграций бота с учётными системами мы используем разработку кастомных модулей, где бизнес-логика живёт в модуле, а бот лишь фронтенд к нему.

Три рабочих сценария из практики

Сценарий	Что делает бот	Экономический эффект	Сложность
Заявки из чатов	Парсит сообщение, создаёт лид/сделку, назначает ответственного по очереди	Минус ручной перенос в CRM, 100% покрытие заявок	Низкая
Напоминания и сроки	Ежедневно шлёт менеджерам список зависших сделок и задач на сегодня	Быстрее реакция на «зависшие» сделки	Средняя
HR-онбординг	Чек-лист новичку, заявки на доступы, напоминания руководителю на 7/30/90 день	HR тратит в разы меньше времени на сопровождение	Средняя

В одном из наших проектов бот «диспетчер заявок» обрабатывает около 300 обращений в день в производственной компании: заявка из общего чеха цеха превращается в задачу механику с автоматическим приоритетом и эскалацией руководителю при просрочке. Ручной координатор больше не нужен.

Сравнение: собственный бот против готовых приложений

Прежде чем писать своего бота, честно оцените решения из Маркетплейса. Типовые сценарии (опросы, уведомления, простые заявки) дешевле закрыть приложением. Процессы с уникальной логикой — распределение по очереди, многошаговые квизы, связка с внутренними системами — требуют собственной разработки. В одном из наших проектов клиент купил три маркетплейс-приложения, а через полгода мы заменили их одним кастомным ботом: дешевле поддерживать один модуль, чем три внешних сервиса.

Развивая сценарий, бота можно подключить к Открытым линиям — тогда клиентские обращения из Telegram и WhatsApp будут попадать в CRM по тем же правилам. Об этом подробно — в статье про интеграцию Битрикс24 с Telegram и WhatsApp.

Типичные ошибки и как их избежать

• Бот как «умный поиск» по справке. Если ответ можно найти в разделе — не дублируйте его ботом, дайте ссылку на раздел базы знаний.
• Синхронные тяжёлые операции. Пока бот ждёт выгрузку из 1С, пользователь смотрит на «печатает…». Всё дольше секунды — в очередь.
• Отсутствие graceful-ответа. Если REST упал, бот обязан сказать «не смог, попробуйте через минуту», а не молчать.
• Нет тестового бота. Отладка на боевом боте с сотрудниками заканчивается недоверием к боту навсегда.
• Игнорирование обновления ядра. Bot API и imbot периодически меняются; бота обновляем вместе с порталом.

Чек-лист перед запуском в продакшен

1. Бот зарегистрирован, BOT_ID и токены в защищённом хранилище, доступ к ним по ролям.
2. Обработчик покрывает все события: сообщение, добавление в чат, команда, ошибка REST.
3. Дедупликация лидов/сделок настроена и проверена на реальных данных.
4. Очередь и логирование работают; по логам можно восстановить любой диалог.
5. Rate limit и защита от спама кнопками включены.
6. Тест на 5–10 добровольцах из целевых подразделений пройден, UX-кнопки и тексты финализированы.
7. Регламент: кому писать, если бот «глухой», и кто следит за логами.

Вывод

• Чат-бот для Битрикс24 — это тонкий клиент к CRM и процессам, а не отдельная система; логика живёт в вашем обработчике.
• Ключевые узлы архитектуры: регистрация через imbot.register, подписка на события, роутинг команд, очередь для тяжёлых операций.
• Интеграция с CRM требует дедупликации, явного источника и ссылки на карточку в ответе.
• Локальный Bot API на коробке — преимущество по безопасности и независимости от внешних сервисов.
• Чек-лист перед продакшеном короче разговоров о нём — но без него бот теряет доверие сотрудников за первую неделю.

FAQ

Можно ли сделать бота в облачном Битрикс24?

Да. Для облака регистрация идёт через публичный REST с внешним вебхуком-обработчиком по HTTPS. Для коробки доступен локальный Bot API внутри периметра. Функционально сценарии идентичны, различаются только требования к инфраструктуре.

Какой стек лучше подходит для обработчика?

Тот, который знает ваша команда: PHP (естественно для коробки), Python или Node.js. Критичны не язык, а очередь, логирование и обработка ошибок REST.

Бот будет работать в мобильном приложении?

Да, чат-боты нативно поддерживаются в веб-версии и мобильных приложениях Битрикс24, включая кнопки и команды.

Сколько стоит разработка чат-бота?

Простой бот с 2–3 сценариями (заявки, справка, напоминания) — от нескольких сотен тысяч рублей и недель работы. Система с очередями, интеграциями и отраслевой логикой — от месяца. Точную смету даём после короткого интервью о процессах.

Чем чат-бот отличается от роботов CRM?

Роботы CRM реагируют на изменения в сущностях (сделка перешла на стадию), бот — на действия сотрудников в чате. Часто их связывают: бот создаёт сущность, роботы двигают её по процессу.

Хотите чат-бота под свои процессы — от заявок до HR-онбординга? Напишите нам — проведём аудит процессов и предложим архитектуру бота с оценкой сроков и бюджета. Также поможем с внедрением облачного Битрикс24, если портал ещё только планируется.