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

Telegram

v1.3.x · обновлено 2026-09-15

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 канала, привязывая агента или фильтруя диалоги по источнику.

Поведение в группах и реакции (коннектор 1.0.2)

Ядро 1.3 закрепляет подписанный коннектор Telegram 1.0.2: он обрабатывает реакции на сообщения, передаёт в ядро корректного отправителя callback-запросов от кнопок и получил настройки поведения в группах. Все они — на карточке коннектора (экран «Каналы» → «Настройка установленных каналов»):

Настройка Что делает
TELEGRAM_REQUIRE_MENTION В группах отвечать только на сообщения с @упоминанием бота (по умолчанию выключено).
TELEGRAM_GROUP_HISTORY_LIMIT / TELEGRAM_DM_HISTORY_LIMIT Сколько сообщений группы или личного чата (0–500) попадает в контекст агента; 0 — по политике агента.
TELEGRAM_GROUP_ACK_REACTION Реакция-эмодзи, которую бот ставит на обращение к нему в группе; пусто — не ставить.
TELEGRAM_FORWARD_REACTIONS Передавать входящие реакции пользователей в ядро как события.
TELEGRAM_GUEST_MODE Гостевой режим: отвечать в любом чате, а не только известным пользователям.
TELEGRAM_ALLOW_BOT_TO_BOT Разрешить обмен с другими ботами (с защитой от циклов).
TELEGRAM_STREAMING Показывать ответ по мере генерации (включено по умолчанию).
TELEGRAM_RICH_MESSAGES Нативные Rich Messages (включено по умолчанию).

Чтобы бот вообще видел сообщения группы, у BotFather должен быть выключен режим приватности (/setprivacy → Disable) — иначе он молчит.

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

Агенты могут общаться с другими ботами. Чтобы это было безопасно, коннектор включает защиту от циклов (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 не нужны.

Куда дальше