AiHummer
Русский▾
ВойтиЛичный кабинет
v1.1.x▾
v1.2.xstablev1.1.xstablev1.0.xstable
{ }Swagger
Каналы/Telegram

Telegram

v1.1.x · обновлено 2026-07-21

Telegram — основной канал, рекомендуемый для первой настройки. Для подключения нужен бот от @BotFather и его токен: создайте бота, передайте коннектору токен — и входящие сообщения начнут поступать в шлюз.

Коннектор Telegram устанавливается из встроенного Маркетплейса и настраивается в админ-панели. Он работает напрямую в Linux (без контейнеров) и общается со шлюзом через API входящих сообщений, поэтому масштабируется и перезапускается независимо от движка обработки запросов.

Подключение Telegram за 6 шагов

Результат: после этих шагов бот отвечает вам в Telegram, а диалог виден в админ-панели на экране «Сессии». Понадобится только аккаунт Telegram и доступ к вашей админ-панели AiHummer.

  1. Создайте бота у BotFather. В Telegram откройте @BotFather, отправьте команду /newbot, задайте имя и username бота. Что вы увидите: BotFather пришлёт токен вида 123456789:AA… — это ключ доступа к боту, скопируйте его.
  2. Установите коннектор Telegram. В админ-панели откройте Маркетплейс, найдите в каталоге коннектор Telegram и нажмите «Установить». Дождитесь, пока карточка перейдёт в статус «онлайн» (виден прогресс установки).
  3. Вставьте токен. Перейдите на экран Каналы → блок «Настройка установленных каналов», откройте карточку Telegram и вставьте токен бота в поле из формы коннектора. Сохраните.
  4. Создайте агента (если ещё не создан) — см. Агенты: достаточно имени и системного промпта.
  5. Привяжите агента к каналу. На экране Каналы в блоке «Привязки» выберите для Telegram агента по умолчанию — правило «новые диалоги в Telegram ведёт агент Y». Выбор сохраняется сразу.
  6. Напишите боту. Откройте вашего бота в Telegram и отправьте ему сообщение. Что вы увидите: агент ответит в чате, а в админ-панели на экране «Сессии» появится соответствующий диалог.

Проверка после настройки: напишите боту с аккаунта, заведённого в системе (или выключите «Отвечать только известным пользователям»). Вы должны увидеть ответ агента в чате и новый диалог на экране «Сессии». Если ответа нет — откройте карточку коннектора на экране «Каналы»: там виден статус доставки и последняя ошибка.

[!NOTE] По умолчанию агент отвечает только известным пользователям (заведённым в AiHummer). Если бот молчит на ваше сообщение — либо добавьте себя как пользователя инстанса, либо на экране Каналы выключите «Отвечать только известным пользователям».

Почему начинать с Telegram

У Telegram наименьший порог входа среди всех каналов AiHummer: нет оператора связи, нет экрана согласия OAuth, нет проверки приложения. Токена бота достаточно, чтобы отправлять и принимать сообщения, и один и тот же коннектор покрывает и внутренние чаты сотрудников, и клиентских ботов. Этот канал поддерживается для промышленной эксплуатации, поэтому именно его мы советуем подключить первым при знакомстве с AiHummer.

Polling или webhook

Коннектор поддерживает оба режима приёма, поэтому работает независимо от того, доступен ли ваш шлюз из публичного интернета.

  • Long polling — коннектор сам забирает обновления у Telegram. Не нужны ни входящий порт, ни TLS, что идеально для локальной разработки и приватных сетей.
  • Webhook — Telegram отправляет обновления на публичный HTTPS-URL. Ниже задержка, лучше подходит для промышленной эксплуатации за обратным прокси, который терминирует TLS.

Коннектор слушает порт 8800 в обычной установке или 8091 при локальном запуске. Каждое входящее сообщение отправляется на URL шлюза из AIHUMMER_INBOUND_URL и аутентифицируется общим входящим секретом.

Rich Messages, реакции и опросы

Помимо обычного текста, канал Telegram отрисовывает Rich Messages — форматированные ответы, которые сопоставляют структурированный вывод агента с нативными возможностями сообщений Telegram. Также поддерживаются реакции и опросы, поэтому агент может отреагировать на сообщение пользователя или поставить быстрый опрос в чат прямо в рамках обработки запроса.

[!TIP] Telegram идентифицируется в AiHummer как канал telegram. Используйте этот id канала, привязывая агента или фильтруя диалоги по источнику.

Бот-к-боту с защитой от циклов

Агенты могут общаться с другими ботами. Чтобы это было безопасно, коннектор включает защиту от циклов (loop guard): он обнаруживает и разрывает неконтролируемые обмены бот-к-боту до того, как они превратятся в бесконечный пинг-понг. Это позволяет собирать мульти-ботовые сценарии без классического сбоя с петлёй обратной связи.

Брокеринг секретов по OIDC

Токен бота и другие секреты коннектора не зашиты в сервис. Вместо этого коннектор получает их на лету из Secrets Service по OIDC — аутентифицируется, а затем забирает нужные доступы. Секреты остаются в зашифрованном хранилище секретов и не попадают в конфигурационные файлы и аргументы процесса.

[!NOTE] Входящие сообщения отправляются на AIHUMMER_INBOUND_URL и защищены общим входящим HMAC-секретом (AIHUMMER_INBOUND_SECRET). Для их диспетчеризации в шлюз должно быть задано рабочее пространство по умолчанию.

Если не получилось

  • Коннектора Telegram нет на экране «Каналы» — сначала установите его на экране Маркетплейс; до установки канал не показывается. На тарифе Community доступен только Telegram; остальные каналы требуют повышения тарифа (HTTP 402).
  • Бот не отвечает на сообщение — проверьте: (1) токен вставлен верно и карточка Telegram «онлайн»; (2) в блоке «Привязки» канал привязан к агенту; (3) отправитель заведён в системе (по умолчанию агент отвечает только известным).
  • Ответы приходят шаблонные — вероятно, ещё работает тестовая модель (mock); подключите провайдера на странице Модели.
  • «Unauthorized» / токен не принят — токен неверный или отозван; сгенерируйте новый у @BotFather (/token) и вставьте заново.
  • Webhook не доходит — если выбран режим webhook, шлюз должен быть доступен по публичному HTTPS-URL; для локальной сети используйте режим long polling — ему входящий порт и TLS не нужны.

Куда дальше