Принимать входящие сообщения от 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 — на усмотрение исполнителя, но желательно хранить в БД, если это соответствует требованиям безопасности в инфраструктуре заказчика.
Callback-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-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
Назначение: чтобы точно знать, какому 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) со структурой, описанной выше.
Пять дней среди диких львов провёл мальчик из Зимбабве
"ИИСУС ИЗ УСБ": "Z" И "АЗ" В НЛП СВО. ДОКЛАД: МОЖНО ОТРАЗИТЬ УГРОЗУ НАРКOТИКОВ ИЗ КОСМОСА. Новости! Россия, США, Европа могут улучшить отношения и здоровье общества?!
«Информация по январю пугающая»: синоптики объявили о новых угрозах в середине зимы
Вильфанд: ледяной дождь и гололед ожидаются в Москве 7 января
