AiHummer
English▾
Sign inAccount
v1.2.x▾
v1.2.xstablev1.1.xstablev1.0.xstable
{ }Swagger
Channels/Telegram

Telegram

v1.2.x · updated 2026-06-26

Telegram is AiHummer’s production-grade, recommended first channel. It is the fastest way to get a working agent in front of real people: create a bot with @BotFather, give the connector the token, and inbound messages start flowing to the gateway.

The Telegram connector is installed from the in-product Marketplace and configured in the Admin UI. It runs host-native and talks to the gateway over the inbound API, so it scales and restarts independently of the turn engine.

Connect Telegram in 6 steps

Here is the end-to-end path from zero to a bot that replies to you in Telegram. All you need is a Telegram account and access to your AiHummer web admin UI.

  1. Create a bot with BotFather. In Telegram open @BotFather, send /newbot, and set the bot’s name and username. What you’ll see: BotFather returns a token like 123456789:AA… — this is the bot’s access key, copy it.
  2. Install the Telegram connector. In the admin UI open Plugins/Marketplace, find the Telegram connector in the catalog and click “Install”. Wait for the card to turn “online” (an install progress bar is shown).
  3. Paste the token. Go to the Channels screen → the “Configure installed channels” block, open the Telegram card and paste the bot token into the field from the connector form. Save.
  4. Create an agent (if you don’t have one yet) — see Agents: a name and a system prompt are enough.
  5. Bind the agent to the channel. On the Channels screen, in the “Bindings” block, pick a default agent for Telegram — the rule “new Telegram conversations are run by agent Y”. The choice saves instantly.
  6. Message the bot. Open your bot in Telegram and send it a message. What you’ll see: the agent replies in the chat, and the matching conversation appears on the “Sessions” screen in the admin UI.

[!NOTE] By default the agent answers only known users (people registered in AiHummer). If the bot stays silent on your message — either add yourself as an instance user, or turn off “Answer only known users” on the Channels screen.

Why start with Telegram

Telegram has the least friction of any AiHummer channel: no carrier, no OAuth consent screen, no app review. A bot token is enough to send and receive messages, and the same connector covers both internal staff chats and customer-facing bots. Because it is production-grade and fully exercised, it is the channel we recommend you wire up first when evaluating AiHummer.

Polling or webhook

The connector supports both ingestion modes, so it works whether or not your gateway is reachable from the public internet.

  • Long polling — the connector pulls updates from Telegram. No inbound port or TLS is required, which makes it ideal for local development and private networks.
  • Webhook — Telegram pushes updates to a public HTTPS URL. Lower latency and better suited to production behind a reverse proxy that terminates TLS.

The connector listens on port 8800 in a normal deployment, or 8091 for a local run. Each inbound message is posted to the gateway URL configured in AIHUMMER_INBOUND_URL, authenticated with the shared inbound secret.

Rich messages, message reactions and polls

Beyond plain text, the Telegram channel renders Rich Messages — formatted replies that map an agent’s structured output onto Telegram’s native message features. It also supports message reactions and polls, so an agent can react to a user’s message or put a quick poll into a chat as part of a turn.

[!TIP] Telegram is the channel identified to AiHummer as telegram. Use that channel id when you bind an agent or filter conversations by source.

Bot-to-bot with a loop guard

Agents can talk to other bots. To make that safe, the connector ships a loop guard: it detects and breaks runaway bot-to-bot exchanges before they turn into an infinite ping-pong. This lets you compose multi-bot workflows without the classic feedback-loop failure mode.

Secret brokering over OIDC

The bot token and other connector secrets are never hard-coded into the service. Instead the connector fetches them at runtime from a Secrets Service over OIDC — it authenticates, then retrieves the credentials it needs. Secrets stay in the encrypted vault and out of config files and process arguments.

[!NOTE] Inbound messages are posted to AIHUMMER_INBOUND_URL and secured by the shared HMAC inbound secret (AIHUMMER_INBOUND_SECRET). The gateway must have a default workspace configured to dispatch them.

If it didn’t work

  • The Telegram connector isn’t on the “Channels” screen — install it first on the Plugins/Marketplace screen; until installed the channel isn’t shown. On the Community plan only Telegram is available; the rest need an upgrade (HTTP 402).
  • The bot doesn’t reply — check: (1) the token is pasted correctly and the Telegram card is “online”; (2) the channel is bound to an agent in “Bindings”; (3) the sender is registered in the system (by default the agent answers only known users).
  • Replies look templated — the mock model is probably still active; connect a provider on the Models page.
  • “Unauthorized” / token rejected — the token is wrong or revoked; generate a new one with @BotFather (/token) and paste it again.
  • The webhook doesn’t arrive — in webhook mode the gateway must be reachable at a public HTTPS URL; on a private network use long polling, which needs no inbound port or TLS.

Where to next