Python (FastAPI) интеграция Telegram и Webim через Custom Channel
1. Цель и общее описание Необходимо создать сервис, который будет:Принимать входящие сообщения от Telegram-бота (через Webhook).Перенаправлять эти сообщения в Webim посредством механизма Custom Channel.Принимать ответы от оператора в Webim (через callback) и пересылать их обратно пользователям в Telegram.Использовать базу данных PostgreSQL:Для хранения настроек (конфигураций, токенов, параметров интеграции).Для хранения связки между Telegram-пользователями и Webim-посетителями (visitor_id ↔ chat_id).При этом сами тексты сообщений (входящие и исходящие) не сохраняются в БД. Хранится только необходимая техническая информация: настройки интеграции и соответствие идентификаторов пользователей в обеих системах. 2. Требования к архитектуре и окружению Язык реализации: Python Web-фреймворк: FastAPI СУБД: PostgreSQLВзаимодействие с Telegram:Через Telegram Bot API и Webhook (setWebhook).Токен бота хранится в БД (таблица настроек) или в .env — на усмотрение исполнителя, но желательно хранить в БД, если это соответствует требованиям безопасности в инфраструктуре заказчика.Взаимодействие с Webim:Через REST API (Custom Channel). https://webim.ru/kb/dev/api/custom-channel.htmlCallback-URL для получения исходящих сообщений от оператора.access_token Webim также хранится в БД (в таблице настроек), либо в .env.Безопасность:Все внешние вызовы должны выполняться по HTTPS.Логирование:Использовать стандартный модуль logging (или аналог) для записи ключевых событий (получение сообщения, отправка, ошибки).Логи можно хранить локально или в любом внешнем сервисе (по согласованию). 3. Функциональные требования 3.1. Обработка входящих сообщений от Telegram Endpoint: POST /telegram-webhookПринимает JSON (update) от Telegram.Извлекает из него:Идентификатор пользователя (chat_id).Текст сообщения (при наличии).Определяет (через обращение к БД) наличие связки chat_id ↔ visitor_id:Если такой записи нет — создаёт новую:Генерирует/запрашивает новый visitor_id (может быть, например, str(chat_id) или использовать GUID).Сохраняет пару visitor_id, chat_id в таблице (см. пункт 4.2).Если запись уже существует, использует соответствующий visitor_id.Отправляет сообщение в Webim по Custom Channel:Передаёт visitor_id, текст сообщения и любую дополнительную метаинформацию (например, username).Сообщения в БД не сохраняются.Регистрация Webhook:Предоставить инструкцию по выполнению setWebhook для Telegram (пример CURL или Python-скрипт). 3.2. Обработка исходящих сообщений от Webim Endpoint: POST /webim-callbackWebim вызывает этот адрес при отправке ответа оператором. По visitor_id ищет в БД связку visitor_id ↔ chat_id.Если связка найдена, получает chat_id.Если нет — логирует ошибку (такое может произойти, если пользователь устарел, или в случае расхождения данных).Отправляет сообщение пользователю в Telegram (метод sendMessage).В БД текст сообщения не сохраняется. 3.3. Хранение настроек в PostgreSQL Хранить токены, URL-адреса и прочие конфигурационные данные в таблице settings. При запуске приложения (FastAPI) читать настройки и использовать в процессе интеграции. Время от времени их можно кэшировать в оперативной памяти, чтобы не грузить БД частыми запросами. 3.4. Хранение связки “visitor_id ↔ chat_id” в PostgreSQL Назначение: чтобы точно знать, какому Telegram-пользователю (chat_id) соответствует конкретный visitor_id из Webim.Предложенная таблица (например, chat_mapping): !Тут на усмотрение разработчика! При первом сообщении от нового Telegram-пользователя сервис создаёт запись (если её ещё нет).При callback из Webim с visitor_id сервис ищет запись в chat_mapping.Важно: если предполагается, что один и тот же Telegram-пользователь может иметь несколько различных сессий (и, соответственно, несколько visitor_id), нужно уточнить бизнес-логику. Наиболее распространённый случай: один chat_id ↔ один visitor_id. 4. Технические детали реализации 4.1. Структура проекта (пример на усмотрения разработчика) project/├── app/
│ ├── main.py # Точка входа FastAPI-приложения
│ ├── config.py # Функции чтения настроек из БД или .env
│ ├── db.py # Подключение к PostgreSQL (SQLAlchemy или psycopg2)
│ ├── routers/
│ │ ├── telegram.py # Маршрут /telegram-webhook
│ │ └── webim.py # Маршрут /webim-callback
│ ├── schemas.py # Pydantic-схемы (валидация входящих данных)
│ └── utils.py # Утилиты (отправка сообщений в Webim/Telegram)
├── requirements.txt # Зависимости (FastAPI, uvicorn, psycopg2 и т.д.)
├── README.md # Инструкция по развёртыванию и настройке
├── .env # Переменные окружения (не хранить в Git)
└── ...
4.2. Взаимодействие с Webim Отправка входящих сообщений:Из telegram.py после получения chat_id и текста вызывается метод utils.send_to_webim(...).В аргументах передаются:visitor_id (из таблицы chat_mapping или вновь созданный).Текст сообщения.Авторизация по access_token Webim (из таблицы settings или переменной окружения).Приём сообщений (callback):В webim.py обрабатывается JSON с полями visitor_id, message, т. д.Находит в БД chat_id.Отправляет ответ в Telegram методами Bot API. 4.3. Взаимодействие с Telegram Отправка сообщений:Метод sendMessage Telegram Bot API.В качестве chat_id используется значение из chat_mapping.Токен бота читается из settings или переменной окружения.Приём сообщений (Webhook):Endpoint POST /telegram-webhook.Извлекает chat_id, текст и затем направляет сообщение в Webim. 4.4. Логирование Записывать в логи каждое входящее и исходящее сообщение (только факт получения/отправки, без сохранения полного текста в БД).При ошибках (например, Telegram вернул 4xx/5xx или Webim не ответил) логировать детальную информацию об ошибке. 5. Выходные материалы Исходный код в репозитории (Git) со структурой, описанной выше.Файлы миграции или SQL-скрипты:Для создания таблицы settings.Для создания таблицы chat_mapping.Инструкция в формате README.md (или аналог):Установка зависимостей (requirements.txt).Настройка переменных окружения (или заполнение таблицы settings).Запуск приложения (например, uvicorn app.main:app --host 0.0.0.0 --port 8000).Настройка Webhook в Telegram (setWebhook).Настройка Webim (callback URL).Пример полного цикла: пользователь → Telegram → Webim → оператор → Webim callback → Telegram.Тестовая сессия:Проверка, что при новом chat_id сервис корректно создаёт новую запись в chat_mapping.Проверка ответа оператора в Webim и доставки этого ответа в Telegram.Убедиться, что сообщения не сохраняются в БД. 6. Критерии приёмки Функциональность:Сообщения из Telegram доходят в Webim, ответы оператора — в Telegram.Связка visitor_id ↔ chat_id создаётся и поддерживается корректно в БД.Настройки (токены и пр.) считываются из PostgreSQL или .env, согласно требованиям.Стабильность:Приложение обрабатывает множественные запросы без критических сбоев.Логи содержат информацию об ошибках, при сетевых сбоях сервис не падает.Качество кода:Соблюдение PEP8 или аналогичных стандартов.Логичная структуризация (роуты, утилиты, модели/схемы).Документация:Наличие полного руководства по запуску/настройке 1-3 станицы.Примеры API-запросов и сценария тестирования.Сроки и соответствие ТЗ:Все перечисленные задачи выполнены.Предоставлен рабочий прототип, готовый к развёртыванию (при условии корректного наполнения таблицы settings и настройки Webim/Telegram).
Backend
