Разработка Битрикс-бота: история о том, как документация врала, а облака смеялись

Привет, Хабр! (И тебе, случайный читатель, который зашёл сюда просто просто потому, что заскучал в корпоративном чате.)

Сегодня я расскажу вам историю о том, какая задача посетила меня на этот раз и как я сделал «корпоративного бота с возможностью оценки сотрудников» — казалось бы, простая задача, но… Нас ждёт много удивительных вещей))

Изначально мой план был такой:

1. Сделать бота в Телеграме.

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

3. Научить его собирать фидбэк о коллегах.

4. Добавить машинное обучение, чтобы он сам выявлял, кто у нас в офисе трудяга, а кто мастерски имитирует бурную деятельность, ну и вообще эмоциональный фон в коллективе).

Но, как это часто бывает в IT, реальность внесла коррективы.

Отдел информационной безопасности посмотрел на мой прототип и сказал:
— «Персональные данные в Телеграме? Ну уж нет, это не по-нашему, не по-православному!»

И вот я стою на распутье: куда же пристроить бота? Или месяц коту под хвост и сказать, что всё это плохая идея и пора завязывать со всем.

Глава 1. Выбор мессенджера: три пути в никуда

Мне предложили три варианта отечественных мессенджеров:

1. VK – «Круто, есть API!» Но…

   • Половина сотрудников им не пользуется.

   • Безопасность? Ха! То аккаунты взламывают, то сам VK их теряет.

     

2. MAX (тот самый «патриотичный» мессенджер) – «Звучит гордо!» Но…

   • Из 250 сотрудников им пользуется ровно один.

   • API выглядит кстати очень здорово (приятно удивило).

3. Битрикс24 – «Он у нас уже есть, сервера свои, все сотрудники уже там!» Идеально, подумал я и начал изучать API? Как бы не так…

Глава 2. Документация Битрикса: игра в угадайку

API Битрикса – это как квест с сюрпризами, болью, слезами и страданием, а ещё в конце появляется скример.

Написано конечно всё классно, плюс/минус понятным языком, жаль конечно, что из примера реализации каждого метода то JS, то PHP, причём реально где-то откроешь метод и там сидит ПХП, а где-то полный набор с cURL, походу зависело от познаний разработчиков. Но вот вопрос, а где Python как можно было забыть этого красавчика.

Ладно, перейдём к примерам…

Открываем метод imbot.message.add – это отправка сообщений от лица бота, здесь у нас PHP

Открываем метод по созданию структуры компании (department.add) и здесь у нас уже полный набор.

И как я понял тот, кто делал API для бота владел одним стеком (PHP), а в остальных разделах API были разносторонние ребята, ну или те, кто умели пользоваться ГПТ, но это на самом деле не очень, важно…

Важно это:

Берём к примеру метод imbot.message.add – простой и понятный метод, отвечающий за отправку сообщений от лица бота. Смотрим на него детальнее…

Красиво? Понятно? – Мне показалось, что да. А теперь хотите узнать, как оно на самом деле?

Да, в KEYBOARD у нас вложился BUTTONS. В BUTTONS вообще массив с перечислением кнопок. CLIENT_ID у нас так же появился из неоткуда, без него вообще запрос возвращал ошибку запрета доступа (скрин со скримером). А MENU где? Его нет.

Как я это понял?

• 5 часов гугления.

• 10 часов перебора вариантов (просто тупо перебора вариантов как бы это могло работать…).

• 1 нервный срыв.

Но самое весёлое – документация врёт нам во многом.

Например, параметр BG_COLOR якобы меняет цвет кнопки. На деле – нет. Есть только четыре предустановленных варианта и то они в BG_COLOR_TOKEN:

И самое забавно, что в примере они типа управляют цветом, но на самом деле используют перезаписанный стиль кнопки.

Кстати, перед тем как, к примеру создавать command в KEYBOARD её ещё надо зарегистрировать в системе Битрикса. Это делается через метод imbot.command.register. Смотрим на пример.

А делаем вот так:

Вывод: Документация Битрикса — как квантовая физика: если кажется, что вы её поняли, значит, вы точно что-то упустили.

Глава 3. Локальный Битрикс? Не смешите мои серверы

Для начала давайте посмотрим, как вообще создаётся бот.

Из раздела «Разработчикам» мы можем попасть в меню выбора разработки.

Для создания бота мы выбираем «Добавить чат-бот», но на самом деле если вы будете делать нечто большее чем просто чат бот с быстрыми командами, то придется попотеть. Но пока не об этом.

После того как мы перешли в «Добавить чат-бот» и перешли следующий пункт (кстати который может у всех отличаться и как я понимаю вы можете брать понравившийся вам) у меня «Информировать сотрудников в чате». Переходим и видим панель создания бота.

Вебхук для вызова rest api – это механизм уведомления одного сервиса другим о произошедших событиях. Но простыми словами и в данном случае это просто API ключ. Иногда когда вы будете менять права доступа своему боту, вам может понадобиться перегенерировать данный ключ.

Создание бота:

Название бота* — Здесь у нас будет название бота таким каким пользователи будут его видеть и находить через поиск по чатам битрикса.

Кстати, если вы хотите изменить картинку боту, то это «ТИПА» можно сделать через запрос imbot.update в формате base64 — но у меня сколько я не пытался не получилось, возможно здесь таже ситуация с неправильной или не актуально докой, я сделал это через «Панель администратора Битрикс», о ней будет в следующем разделе.

URL обработчика бота* — это, пожалуй, самая важная штука. Сюда мы указываем адрес нашего сервера, на котором мы будем слушать обращения. Это нужно, чтобы, к примеру, когда пользователь пишет боту сообщение, или запускает команду, бот нам слал Сообщение.

А теперь перейдём к самой теме…

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

Игра «Кто хочет стать разработчиком Bitrix-бота»:

И тут «A» понятно, что шутка. «С» – порт мы пробросили через NAT, что бы он пинговал мою машину. «D». Тут как бы не столь критично, но самогенерированный (псевдо) сертификат hpps мы сделали. А верный ответ «B».

У нас on-premise версия Битрикса (чтобы всё было на наших серверах).

Но вот загадка:

Почему запросы от бота идут через облако сторонней компании?

Разгадка:

• Бот отправляет сообщение → запрос улетает на Corp Soft, Seleznevskaya street, 32 (это облачный провайдер Битрикса) и он такой не один, мы так же поймали как минимум пять ip VK (походу он так сильно хотел нашего бота).

• Вопрос: Зачем гонять трафик через третьи лица, если у нас локальная версия?

Теории:

• Кто-то накосячил в архитектуре.

• Это фича, а не баг (чтобы мы купили облако).

Это весьма интересный вопрос, от которого вообще теряется весь смысл on-prem поставки продукта. Ведь нельзя было использовать мощности сервера для отправки запроса, зачем гонять трафик через 3-х лиц. Короче мне кажется, что здесь кто-то просто сильно накосячил.

Глава 4. Бот, который боится файлов

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

Вы создали бота под себя — вы его автор и владелец, царь и бог. Однако Битрикс сохраняет все файлы на Битрикс Диск в каталоге чата. Но бот — это не совсем вы. Он должен самостоятельно обрабатывать переданные файлы через свой вебхук, а не полагаться на ваши права.

К сожалению, стандартного решения нет. В интернете я нашёл только информацию о платных подписках на «супер-пупер бота», который решает эту проблему. Но мы же разработчики-экспериментаторы!

Решение?

• Получаем права администратора (каждый делает это по-своему). И заходим в администрирование Bitrix.

• Находим бота среди пользователей (извините, скриншотов не будет — это конфиденциально).

• Выдаём ему права обычного сотрудника (чтобы он не выделялся).

• Авторизуемся под ботом через кнопку «Авторизоваться под сотрудником» в Панеле администрования Bitrix.

• Настраиваем персональный вебхук для бота (как показано на скриншотах).

Даём права в «Настройка прав». А лучше сразу дать всё чтобы больше не лазить сюда. Копируем сформированный Вебхук. Закрываем и забываем как страшный сон.

И получается у нас смешная картина. Мы сделали бота, наделили его правами создателя, а затем воскресили его (превратив в сотрудника) и выдали ему ещё токен под его правами, и теперь у нас есть 2 токена (1 супер крутой – принадлежит боту, другой простенький и принадлежит нам), и пишем код, который будет маршрутизировать использование прав в зависимости от ситуаций. Не хотите писать, я уже написал, правда не судите строго))

import json import requests import itertools from typing import Dict, Any, List, Optional  class Bitrix24API:     """Класс для работы с REST API Bitrix24 через вебхук(и)"""     def __init__(self, webhook_url: str, array_webhooks: Optional[List[str]] = None, logger=None, fetch_all_pages: bool = True, page_size: int = 50):         """         Инициализация класса с URL вебхука(ов) Bitrix24         ---         :param webhook_url: URL вебхука Bitrix24         :param array_webhooks: Список альтернативных вебхуков для перебора         :param logger: Объект логирования от библиотеки logging         :param fetch_all_pages: Автоматически загружать все страницы при пагинации         :param page_size: Количество элементов на странице (по умолчанию 50)         """         self.webhook_url = webhook_url         self.array_webhooks = array_webhooks or []         self.logger = logger         self.specifically = None         self.fetch_all_pages = fetch_all_pages         self.page_size = page_size      # ---Внутрение методы---     def _try_call_method(self, webhook_url: str, method: str, params: Dict[str, Any]) -> Optional[Dict[str, Any]]:         """Внутренний метод для попытки вызова метода через конкретный вебхук"""         url = f"{webhook_url}{method}"         try:             response = requests.post(url, json=params)             response.raise_for_status()             result = response.json()             if 'error' in result:                 if self.logger: self.logger.error(f"Bitrix API ошибка в '{webhook_url}': {result['error']}")                 return None             if self.logger:  self.logger.info(f"Запрос к Bitrix API выполнен успешно - method: {method} - 200")             return result         except requests.exceptions.RequestException as e:             if self.logger:  self.logger.error(f"Ошибка запроса в '{webhook_url}': {e}")             return None         except json.JSONDecodeError as e:             if self.logger: self.logger.error(f"Ошибка декодирования JSON в '{webhook_url}': {e}")             return None      def _call_with_pagination(self, webhook_url: str, method: str, params: Dict[str, Any], start: int = 0) -> Optional[Dict[str, Any]]:         """         Внутренний метод для обработки пагинации         ---         :param webhook_url: URL вебхука         :param method: Метод API         :param params: Параметры запроса         :param start: Смещение для пагинации         :return: Объединенный результат или None при ошибке         """         params = params.copy()         params['start'] = start         result = self._try_call_method(webhook_url, method, params)         if not result: return None         if not self.fetch_all_pages or 'next' not in result or start > 0: return result.get('result')         # Если нужно получить все страницы и это первый запрос         total = result.get('total', 0)         if total <= self.page_size:             return result.get('result')         # Вычисляем количество дополнительных запросов         count_pages = (total // self.page_size) - (1 if total % self.page_size == 0 else 0)         # Собираем результаты со всех страниц         all_results = [result.get('result', [])]         for page in range(1, count_pages + 1):             next_result = self._call_with_pagination( webhook_url, method, params, page * self.page_size)             if next_result is not None: all_results.append(next_result)         # Объединяем результаты         if isinstance(all_results[0], list):             return list(itertools.chain.from_iterable(all_results))         elif isinstance(all_results[0], dict):             merged = {}             for res in all_results: merged.update(res)             return merged         return all_results[0]      # ---Внешние методы---     def callMethod(self, method: str, params: Optional[Dict[str, Any]] = None,                    specifically: Optional[str] = None) -> Any:         """         Отправляет запрос к Bitrix24 REST API с поддержкой пагинации         ---         :param method: Метод API (например, "crm.deal.list")         :param params: Параметры запроса в виде словаря         :param specifically: Конкретный вебхук для использования         :return: Ответ от сервера Bitrix24 или None в случае ошибки         """         if params is None: params = {}         webhooks_to_try = []         if specifically is not None: webhooks_to_try = [specifically]         else:             if self.webhook_url: webhooks_to_try.append(self.webhook_url)             webhooks_to_try.extend(self.array_webhooks)         for webhook in webhooks_to_try:             result = self._call_with_pagination(webhook, method, params)             if result is not None: return result         if self.logger:             self.logger.error(f"Запрос к Bitrix API никак не отработал {method}, {params}")         return None   # # ==================================== # # ----------Пример использования------ # if __name__ == "__main__": #     # Инициализация клиента с несколькими вебхуками #     main_webhook = "https://...Токен_Бота" #     backup_webhooks = ["https://...Токен_Разработчика", "https://...Токен_Васи_Пупкина", "https://...Токен_ФигЗнаетКого"]      #     bitrix = Bitrix24API(webhook_url=main_webhook, array_webhooks=backup_webhooks, logger=C.LOGGER_BITRIX_API) #     result = bitrix.callMethod("calendar.section.get", {"type": "user", "ownerId": "0"}, specifically="https://...Токен_Разработчика") #     print(result) # # ====================================

Итоговая схема:

Вот такую я нарисовал схему взаимодействия, на первый взгляд возможно не очевидную.

Вывод: кто виноват и что делать?

• Документация Битрикса – это квест. Гугл и метод тыка спасают.

• «Локальный» Битрикс иногда ведёт себя как облачный.

• Боты боятся файлов, пока не дашь самостоятельность боту (а это может быть страшно).

Мораль:
Если ваш бот в Битриксе работает с первого раза – проверьте, не снится ли вам это.

P.S. В следующей статье расскажу, как сделать боту ролевую модель, научить бота отвечать на любые произвольные команды пользователя, подружить его с СУБД , заставить этого бота анализировать сотрудников (и не сойти при этом с ума).