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

Интеграция с Telegram

Telegram-шлюз — отдельный внешний сервис, который соединяет Telegram-бота с платформой Synth. Он превращает сообщения из чата во внешние события и доставляет ответы агента обратно в чат.

Шлюз — самостоятельный сервис со своим репозиторием, образами и деплоем; с Synth он общается только по публичным контрактам (API событий и сессий).

Как это работает

Telegram Bot API        synth-gateway-telegram             Synth API
   getUpdates ─long-poll─▶ поллер ─normalize─▶ POST /api/v2/events
                                  │                       │
   sendMessage ◀─watcher ◀─ SSE GET /api/v2/events ◀─ события сессии
  1. Шлюз опрашивает Telegram (long-polling getUpdates) и нормализует входящие сообщения и нажатия кнопок во внешние события.
  2. События публикуются в Synth (POST /api/v2/events); ядро маршрутизирует их в сессию ( События и автоматизация).
  3. Ответ агента шлюз получает по потоку событий (SSE) и отправляет обратно в чат — со стримингом по мере генерации.

Что умеет

  • Стриминг ответа — сообщение появляется в чате и дописывается по мере ответа агента.
  • Индикатор «печатает…» — показывается, пока идёт генерация.
  • Остановка ответа — команда /stop прерывает активный ответ агента.
  • Привязка чата — команды /bind и /unbind закрепляют чат за сессией.
  • Служебные команды — /help, /start, /status.
  • Форматирование — режим отправки (parseMode): plain, html (Markdown → Telegram-HTML) или markdown (расширенные таблицы, заголовки, списки и стриминг черновиком в приватных чатах).
  • Ответ-реплай на источник — ответ приходит reply-ем на то сообщение, на которое отвечает агент.

В чатах работает список доступа: отправители вне списка не публикуются в Synth.

MCP-инструменты для агента

Шлюз отдаёт агенту MCP-инструменты (с префиксом tg_) — отправка, правка и удаление сообщений, уведомления, inline-кнопки, отправка сообщения конкретному пользователю. Они подключаются как обычные MCP-инструменты.

Несколько ботов

Один шлюз обслуживает несколько ботов: каждый бот привязан к своей среде Synth, а конфигурация задаётся файлом tenants.json (тенант — id, токен бота, адрес Synth, учётные данные, список доступа, прокси, режим отправки). Состояние тенантов изолировано; один бот = один опрос Telegram, поэтому конфликтов между ботами нет.

Учётные данные Synth

Шлюз аутентифицируется в Synth по приоритету: service-ключ → OIDC → API-ключ.

  • Рекомендуется service-ключ ( service-ключи). Для сквозного контура (приём событий + обратная доставка) достаточно scopes events:ingest, events:watch.
  • OIDC — как запасной вариант для серверных развёртываний.
  • API-ключ — для локального запуска.

Развёртывание

  • Шлюз разворачивается отдельно: Docker, docker compose или Helm-чарт synth-gateway-telegram.
  • Опубликованные артефакты: образ gitverse.ru/itphx/synth-gateway-telegram и Helm-чарт из публичного реестра Synth.
  • Один бот — один опрос. Не запускайте два поллера на один и тот же токен: второй получит конфликт от Telegram (для надёжности используется одна реплика).
  • Для Bot API может требоваться HTTP-прокси; запросы OIDC идут напрямую.

Токены — в секретах

Токены ботов, service-ключи и токены MCP храните в секретах (Secret / файлы вне репозитория) и не допускайте их попадания в логи.

Что дальше