BitrixDealsBot

BitrixDealsBot — это телеграм-бот, который позволяет пользователям взаимодействовать с CRM-системой Bitrix24 для управления сделками и контактами. Цель бота — упростить процесс работы с CRM, предоставляя удобный интерфейс для обновления и отслеживания сделок прямо из Telegram.

Задание выполняется в рамках учебной производственной практики для предприятия ООО "Интернет-агенство ИНТЕРВОЛГА".

Формулировка задания

Telegram-бот “Помощник менеджера CRM”

Telegram-бот для менеджера по продажам. Бот помогает быстро смотреть новые лиды, брать их в работу, менять статус и добавлять комментарии.

Стек: Любой язык, любая БД, REST API Telegram, REST API Битрикс24

Функции:

• команда /leads показывает новые лиды (без ответственных);
• команда /lead ### показывает карточку лида по указанному ID: имя, телефон, источник, статус;
• кнопка “Взять” устанавливает ответственного;
• кнопка “Позвонить позже” устанавливает ответственного и планирует звонок через 1 час;
• кнопка “Закрыть” возвращает в список лидов /leads;
• команда /history показывает историю действий;
• интеграция с Битрикс24 через webhook (Был осуществлен переход на OAuth).

Архитектура решения

Основные архитектурные решения изложены в разделе ADR (Architecture Decision Records) в папке docs/adr. Главный документ может использоваться для навигации между заметками о принятых решениях.

Настройка

Important

Для развертывания проекта требуется Docker и Docker Compose. В Windows рекомендуется использовать WSL2. Также требуется внешний nginx для проксирования запросов к сайту.

Клонируйте репозиторий и перейдите в папку проекта:

cd BitrixDealsBot

Скопируйте .env.example в .env и заполните значения. Ключ шифрования можно создать командой:

python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"

TOKEN_ENCRYPTION_KEY должен быть одинаковым у сайта и бота. В БД OAuth-токены попадают уже зашифрованными.

Сгенерируйте или иным способом придумайте пароли для ролей администратора, пользователя сайта и бота. В PostgreSQL роли создаются автоматически при первом создании контейнера db.

Также укажите URL, который будет использоваться в качестве базового адреса сайта. Соответственно, для этого бы желательно иметь свой домен, соответствующие DNS-записи и TLS-сертификат (например, от Let's Encrypt).

Создайте локальное приложение в Битрикс24 и укажите в нем URL для привязки:

https://bot.example.ru/bitrix/bind

Битрикс сгенерирует CLIENT_ID и CLIENT_SECRET, которые нужно указать в .env. В настройках приложения разрешите доступ к CRM и к минимальной информации о пользователе. Битрикс передает сайту OAuth-данные приложения. Сайт обменивает REFRESH_ID на новую пару токенов и берет доверенные идентификаторы портала и пользователя из ответа OAuth-сервера. Затем он проверяет пользователя через user.current, сохраняет зашифрованную пару токенов и показывает ссылку на Telegram.

Также создайте бота в Telegram через BotFather и укажите его токен в .env. Дополнительно укажите в .env имя вашего бота, которое будет использоваться в ссылках на него.

Вы также можете изменить в '.env' стандартную стадию сделки, которая будет использоваться при взятии сделки в работу. По умолчанию это стадия "C1:PREPARATION". Если вы хотите использовать другую стадию, укажите ее код в переменной BITRIX_TAKE_TO_WORK_STAGE_ID.

Запуск в Docker

docker compose up --build -d

Создаются четыре контейнера:

• db — PostgreSQL без опубликованного порта;
• site — Flask/Gunicorn на 127.0.0.1:8000 хостовой машины;
• bot — aiogram polling без входящего порта;
• migrate — контейнер для миграции БД, запускается при каждом docker compose up и завершается после выполнения миграций.

Инициализация БД выполняется автоматически только для нового volume.

Внешний nginx

Nginx работает на хосте, вне Docker:

location / {
    proxy_pass http://127.0.0.1:8000;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
}

Если на вашем сервере есть панели типа FastPanel, Plesk, ISPmanager, то вы можете создать сайт с обратным прокси прямо в интерфейсе панели.

Транзакции и доступ к БД

Сайт подключается ролью site_app, бот — bot_app. Прямого доступа к таблицам у них нет.

• binding.issue_v1 сохраняет OAuth-данные и выпускает ссылку одной транзакцией.
• binding.consume_v1 атомарно погашает ссылку и создает привязку.
• oauth.* выдает и обновляет токены только боту.
• короткая DB-аренда защищает refresh-токен от параллельного обновления.

Сетевые запросы к Битриксу не выполняются внутри транзакций. Назначения на сделки хранятся только в Битриксу. Локальная блокировка в процессе бота не дает двум Telegram-пользователям одновременно взять одну сделку, а повторная проверка ASSIGNED_BY_ID отсекает устаревшие кнопки.

Команды бота

• /start bind_<token> — привязать пользователя.
• /deals или /leads — показать сделки с фильтром и пагинацией.
• /deal 123 — открыть карточку сделки.
• /help — показать справку.

Фильтр «Мои сделки» показывает сделки всех стадий, где ответственным назначен привязанный Битрикс-пользователь.

Кнопка «Позвонить позже» создает дело с напоминанием в Битриксе через час. История показывает пять последних переходов сделки по стадиям. Кнопка «Стать ответственным и взять в работу» использует ID привязанного Битрикс-пользователя. Ответственный также видит кнопку перехода на следующую стадию; финальный переход выделен как завершение сделки. Перед переходом бот запрашивает необязательный комментарий для таймлайна: пустая строка или прочерк означают переход без него.