Python (FastAPI) интеграция Telegram и Webim через Custom Channel

1. Цель и общее описание

1. Принимать входящие сообщения от Telegram-бота (через Webhook).
2. Перенаправлять эти сообщения в Webim посредством механизма Custom Channel.
3. Принимать ответы от оператора в Webim (через callback) и пересылать их обратно пользователям в Telegram.
4. Использовать базу данных PostgreSQL:
   • Для хранения настроек (конфигураций, токенов, параметров интеграции).
   • Для хранения связки между Telegram-пользователями и Webim-посетителями (visitor_id ↔ chat_id).

2. Требования к архитектуре и окружению

1. Язык реализации: Python
2. Web-фреймворк: FastAPI
3. СУБД: PostgreSQL
4. Взаимодействие с Telegram:
   • Через Telegram Bot API и Webhook (setWebhook).
   • Токен бота хранится в БД (таблица настроек) или в .env — на усмотрение исполнителя, но желательно хранить в БД, если это соответствует требованиям безопасности в инфраструктуре заказчика.
5. Взаимодействие с Webim:
   • Через REST API (Custom Channel). https://webim.ru/kb/dev/api/custom-channel.html
   • Callback-URL для получения исходящих сообщений от оператора.
   • access_token Webim также хранится в БД (в таблице настроек), либо в .env.
6. Безопасность:
   • Все внешние вызовы должны выполняться по HTTPS.
7. Логирование:
   • Использовать стандартный модуль logging (или аналог) для записи ключевых событий (получение сообщения, отправка, ошибки).
   • Логи можно хранить локально или в любом внешнем сервисе (по согласованию).

3. Функциональные требования

3.1. Обработка входящих сообщений от Telegram

1. Endpoint: POST /telegram-webhook
   
   
   • Принимает JSON (update) от Telegram.
   • Извлекает из него:
     • Идентификатор пользователя (chat_id).
     • Текст сообщения (при наличии).
   • Определяет (через обращение к БД) наличие связки chat_id ↔ visitor_id:
     • Если такой записи нет — создаёт новую:
       1. Генерирует/запрашивает новый visitor_id (может быть, например, str(chat_id) или использовать GUID).
       2. Сохраняет пару visitor_id, chat_id в таблице (см. пункт 4.2).
     • Если запись уже существует, использует соответствующий visitor_id.
   • Отправляет сообщение в Webim по Custom Channel:
     • Передаёт visitor_id, текст сообщения и любую дополнительную метаинформацию (например, username).
   • Сообщения в БД не сохраняются.
2. Регистрация Webhook:
   
   
   • Предоставить инструкцию по выполнению setWebhook для Telegram (пример CURL или Python-скрипт).

3.2. Обработка исходящих сообщений от Webim

1. Endpoint: POST /webim-callback
   • Webim вызывает этот адрес при отправке ответа оператором.
   • По visitor_id ищет в БД связку visitor_id ↔ chat_id.
     • Если связка найдена, получает chat_id.
     • Если нет — логирует ошибку (такое может произойти, если пользователь устарел, или в случае расхождения данных).
   • Отправляет сообщение пользователю в Telegram (метод sendMessage).
   • В БД текст сообщения не сохраняется.

3.3. Хранение настроек в PostgreSQL

• Хранить токены, URL-адреса и прочие конфигурационные данные в таблице settings.
  

• При запуске приложения (FastAPI) читать настройки и использовать в процессе интеграции. Время от времени их можно кэшировать в оперативной памяти, чтобы не грузить БД частыми запросами.

3.4. Хранение связки “visitor_id ↔ chat_id” в PostgreSQL

1. Назначение: чтобы точно знать, какому Telegram-пользователю (chat_id) соответствует конкретный visitor_id из Webim.
   
2. Предложенная таблица (например, chat_mapping):
   
   

   !Тут на усмотрение разработчика!

   • При первом сообщении от нового Telegram-пользователя сервис создаёт запись (если её ещё нет).
   • При callback из Webim с visitor_id сервис ищет запись в chat_mapping.
3. Важно: если предполагается, что один и тот же 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. Выходные материалы

1. Исходный код в репозитории (Git) со структурой, описанной выше.
2. Файлы миграции или SQL-скрипты:
   • Для создания таблицы settings.
   • Для создания таблицы chat_mapping.
3. Инструкция в формате 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.
4. Тестовая сессия:
   • Проверка, что при новом chat_id сервис корректно создаёт новую запись в chat_mapping.
   • Проверка ответа оператора в Webim и доставки этого ответа в Telegram.
   • Убедиться, что сообщения не сохраняются в БД.

6. Критерии приёмки

1. Функциональность:
   • Сообщения из Telegram доходят в Webim, ответы оператора — в Telegram.
   • Связка visitor_id ↔ chat_id создаётся и поддерживается корректно в БД.
   • Настройки (токены и пр.) считываются из PostgreSQL или .env, согласно требованиям.
2. Стабильность:
   • Приложение обрабатывает множественные запросы без критических сбоев.
   • Логи содержат информацию об ошибках, при сетевых сбоях сервис не падает.
3. Качество кода:
   • Соблюдение PEP8 или аналогичных стандартов.
   • Логичная структуризация (роуты, утилиты, модели/схемы).
4. Документация:
   • Наличие полного руководства по запуску/настройке 1-3 станицы.
   • Примеры API-запросов и сценария тестирования.
5. Сроки и соответствие ТЗ:
   • Все перечисленные задачи выполнены.
   • Предоставлен рабочий прототип, готовый к развёртыванию (при условии корректного наполнения таблицы settings и настройки Webim/Telegram).