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

35 000 руб. за проект
05 января 2025, 04:27 • 5 откликов • 16 просмотров

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).

Поделиться