Перейти к содержанию

Telegram‑бот

Telegram‑бот — это сервис telegram-bot/, который обслуживает текстовый канал в Telegram Business. Он принимает входящие сообщения по webhook, с помощью MCP‑инструмента verify_user сопоставляет Telegram‑пользователя (tg_id) с внутренним user_id, записывает историю переписки в таблицу dialogue_history MariaDB и обращается к OpenAI Responses API. Если MCP‑сервер доступен, бот дополнительно использует его инструменты для работы с заявками и другой доменной логикой.

Жизненный цикл запроса

Поток обработки бизнес‑сообщения можно представить как несколько последовательных шагов. Telegram отправляет update на заранее настроенный webhook URL. aiohttp‑приложение в main.py принимает HTTP‑запрос, передаёт его в aiogram через SimpleRequestHandler, и тот вызывает обработчик handle_business_message из handlers/messages.py.

handle_business_message сначала отфильтровывает исходящие сообщения бизнес‑аккаунта и разделяет два сценария:

  • текст — делегирует обработку в utils/ai_processor.process_ai_request, передавая примитивные поля (tg_id, request_text, message_id, business_connection_id);
  • документ — принимает Word (.doc/.docx) или PDF (.pdf), проверяет сигнатуру файла, сохраняет его на диск и пересылает ответственному аккаунту (см. services/signed_documents.py и services/telethon_sender.py).

Внутри process_ai_request входящее сообщение помечается прочитанным (если есть business_connection_id), определяется user_id через MCPIdentityResolver (services/identity.py, MCP‑инструмент verify_user), при необходимости из текста извлекается телефон и сохраняется в users.phone (через MySQLMemory). Затем сообщение передаётся в OpenAIService.process_message.

Обычный запрос после всех этих шагов попадает в OpenAIService.process_message (services/openai/service.py). Этот метод собирает историю диалога через ConversationManager, строит текстовый контекст, формирует инструкции (InstructionProvider) и, если MCP доступен, добавляет конфигурацию инструментов (ToolRegistry) к вызову OpenAI Responses API. Модель получает текущий запрос вместе с краткой историей и, при необходимости, обращается к MCP‑инструментам. Ответ модели возвращается в виде строки, фиксируется в истории диалога и отправляется пользователю в Telegram. Таким образом, все слои — HTTP, идентификация, память и OpenAI — связаны в один, достаточно прямолинейный поток.

Отдельно, HTTP‑сервер бота предоставляет служебные эндпоинты POST /cargo-assigned и POST /cargo-docx. Их вызывает MCP‑сервер: для уведомлений и отправки DOCX пользователю. Контракты (структура запросов, коды ошибок, примеры curl) описаны на странице HTTP API (служебные эндпоинты).

В виде последовательности этот поток можно описать так:

uml diagram

Общая схема работы

На минимальном уровне сценарий обработки сообщения можно представить так:

@router.business_message()
async def handle_business_message(message: Message):
    if not _is_incoming_business_message(message):
        return
    if message.document:
        await _handle_business_document(message)
        return
    await _handle_business_text(message)

Обработчик получает объект Message, игнорирует исходящие сообщения бизнес‑аккаунта, разделяет входящие события на текст и документы и делегирует обработку текста в process_ai_request, передавая значения полей явно. Внутри process_ai_request определяется user_id через MCP‑инструмент verify_user, при необходимости сохраняется телефон, а затем текст передаётся в OpenAIService.process_message. Ответ модели отправляется пользователю и записывается в историю диалога.

HTTP‑слой реализован на базе aiohttp. В main.py создаётся приложение, подключается middleware для логирования запросов и настраивается обработчик webhook для aiogram. Конфигурация бота (BOT_TOKEN, адрес и путь webhook, параметры HTTP‑сервера, настройки БД и OpenAI) читается через класс Config из модуля config/settings.py. Обработчики сообщений организованы в handlers/messages.py, а основная бизнес‑логика — в функции process_ai_request из utils/ai_processor.py.

Связка с MCP‑сервером вынесена в отдельные компоненты. Класс MCPIdentityResolver (services/identity.py) сопоставляет tg_id → user_id через инструмент verify_user. Класс OpenAIService (services/openai/service.py) управляет историей диалога через MySQLMemory и ConversationManager, строит инструкции, вызывает Responses API и подключает MCP‑инструменты через ToolRegistry, если они доступны.

Эта страница даёт только общий контекст. За подробностями можно перейти в разделы про архитектуру HTTP‑слоя, конфигурацию окружения и работу с OpenAI и MCP‑инструментами.