# Telegram

Source: https://www.hyperagent.com/docs/concepts/agents/invocations/telegram

> For AI agents: the documentation index is at https://www.hyperagent.com/llms.txt and the complete documentation in one file at https://www.hyperagent.com/llms-full.txt. Any docs page is also served as Markdown by appending `.md` to its URL.

Bring your agent into Telegram: the bot connection, account pairing, group authorization, and how media and replies flow both ways.

You want to reach your agent from your phone the way you'd message a colleague: a quick DM on the train, a report dropped into a team group, a voice note when your hands are full. Telegram is where the agent meets you; the bot you connect is just the doorway, tied to your account, so the agent answers the people you chose and not everyone who stumbles onto the username.

Connect a bot as the doorway, pair it to your account so the agent recognizes
you, and decide chat by chat who can reach it. Every conversation becomes a
lasting thread.

## How Telegram works [#how-telegram-works]

A Telegram bot gives the agent a name, username, and place to receive
messages. Its token connects that bot to one Hyperagent agent.

A one-time link ties your Telegram user ID to the bot. The paired account
becomes the owner who can use it in DMs and authorize it in groups.

Direct messages are owner-only. In groups, you choose who can reach the
agent and which kinds of messages start a run.

Every DM, group, or forum topic maps to a lasting Hyperagent thread, keeping
its conversation and replies in the right place.

## Connect your agent to Telegram [#connect-your-agent-to-telegram]

The doorway is a Telegram bot, and Telegram bots are created inside Telegram, so setup starts with a token from BotFather and ends with the agent recognizing you. On the agent's **Invocations** tab, open the Telegram control and the **Connect Telegram Bot** dialog walks the same three steps:

### Create the bot in Telegram [#create-the-bot-in-telegram]

Message @BotFather, send `/newbot`, then choose a name and username. The username must end in `bot`; the description is optional. This bot is your agent's face in Telegram, so name it like the agent rather than like infrastructure. Copy the token BotFather returns.



### Paste the token and connect [#paste-the-token-and-connect]

Paste the token into the **Bot Token** field. Hyperagent validates it live against Telegram, and a valid token surfaces a green confirmation with the bot's `@username` and display name so you can be sure you pasted the right one. **Connect** stays disabled until validation succeeds.



### Pair with your Telegram account [#pair-with-your-telegram-account]

Connecting proves the bot is real; pairing proves *you* are the owner. Select **Open Telegram to pair**, then tap **Start** in Telegram. That stamps your Telegram identity onto the connection, and the agent replies "You're paired with Hyperagent. You can now chat with your agent here."

Telegram identifies people by numeric user ID, which Hyperagent can't know until you pair. Before that link stamps your ID onto the connection, the agent can't distinguish you from a stranger, so an unpaired bot answers no DMs.

The link is single-use and expires after 15 minutes. The dialog shows the
exact expiry time; if it lapses, generate a new one.





Use **Re-pair** when the owning Telegram account changes. Re-pairing resets the bot's thread mappings so the new owner doesn't inherit the previous owner's conversation history; existing chat threads start fresh.

One bot belongs to one agent, and one token belongs to one bot everywhere on
the platform. Reconnecting a fresh token from BotFather replaces the old
binding. Your raw token is never stored in plaintext; it lives in the secret
store, and the database keeps only the bot's numeric ID and username.

## Control who can use the bot [#control-who-can-use-the-bot]

Pairing establishes the owner. From there, direct messages and groups follow different access rules: DMs stay private to that owner, while each group must be explicitly authorized before anyone can use the agent there.

### Direct messages [#direct-messages]

Anyone who finds your bot's username can open a chat with it, but only the paired owner gets answers. The bot matches every incoming DM against its pairing record, and messages from any other account aren't routed to the agent.

The first time a non-owner messages the bot in a given hour, it replies once with a fixed notice:

> Sorry, I'm not configured to respond to you. Contact the bot owner for access.

Further DMs from that person within the hour are dropped silently. The first reply tells a legitimate person they've reached the wrong bot; the silence that follows keeps the bot from being used to spam them.

### Add the bot to a group [#add-the-bot-to-a-group]

A bot sitting in a group does nothing until you've allowed group chats on the bot and authorized that specific group from inside it. Being added isn't authorization: Telegram lets anyone add a bot to a group, so Hyperagent waits for the paired owner to approve it.

### Allow group chats [#allow-group-chats]

In the manage dialog, turn on **Allow group chats**. It's off by default. This reveals the group settings and lets the bot accept authorization.

### Add the bot to the group [#add-the-bot-to-the-group]

Add your bot from the group's member list.

### Authorize the group [#authorize-the-group]

Send `/authorize` in the group as the paired owner. Commands from anyone else are silently ignored. On success, the bot replies "Group authorized. Members can now talk to me based on this bot's settings."

Until the group is authorized, every message in it is dropped. The `/authorize` command is checked before response-trigger filtering, so it works regardless of the trigger mode you've chosen.

### Choose who can trigger the agent [#choose-who-can-trigger-the-agent]

An authorized group inherits the bot's **Default for new groups** policy at that moment, then keeps its own copy. Changing the default later doesn't rewrite existing groups, and you can override each group's policy from its row in the manage dialog.

Only the paired owner's messages trigger the agent. Everyone else's are
ignored, which suits a group where the agent is present but reports only to
you.

Any member can trigger the agent. Non-owners are limited to roughly one
message every three seconds each; the owner isn't rate limited.

### Choose when the bot responds [#choose-when-the-bot-responds]

The access policy decides *whose* messages count. The response trigger decides *which* of those messages start an agent run, so a busy group doesn't turn every line into work. This setting is shared by all of the bot's groups under **When should I respond?**

The bot reacts when someone @mentions it or replies directly to one of its
messages, and stays quiet otherwise.

The bot reacts only to `/commands` or direct replies. This is the one mode
that works with Telegram privacy mode left on.

Every eligible message in an authorized group starts a run. Telegram privacy
mode must be turned off.



### Configure Telegram privacy mode [#configure-telegram-privacy-mode]

Telegram privacy mode is on by default and determines which group traffic Telegram forwards to the bot. With it on, only `/commands` and direct replies to the bot's own messages reach Hyperagent. That makes **Commands or replies** the only mode that works without changing BotFather.

When you choose **@mentions or replies**, Hyperagent recommends turning privacy mode off because plain @mentions aren't forwarded while it remains on. **Every message** requires it: Telegram won't send ordinary group messages to the bot otherwise. The manage dialog shows a warning when the selected trigger needs this change.

Message @BotFather, send `/setprivacy`, pick your bot, and choose **Disable**.
Privacy changes only take effect when the bot joins, so remove and re-add it
to any existing group.



## How Telegram conversations work [#how-telegram-conversations-work]

### Threads and topics [#threads-and-topics]

Every Telegram chat maps to a lasting Hyperagent thread named "Telegram chat." That thread is the record; there isn't a separate Telegram run history.

The conversation with the paired owner stays together in one thread.

A regular group maps to one thread, so its messages and replies keep the
same context.

Each Telegram topic gets its own thread, keeping parallel conversations and
replies separate.

Thread trust follows the setting. DM threads are treated as user-facing. Group and supergroup threads are treated as external for memory auto-accept because anyone in the group may contribute to them.

### Messages and media [#messages-and-media]

Attachments are routed into the thread and identified by their actual bytes rather than Telegram's label. Each attachment is capped at 20 MB. When a file is too large, the agent is told that it couldn't take it in and can ask for a smaller version.

| You send        | The agent gets                                                                                                              |
| --------------- | --------------------------------------------------------------------------------------------------------------------------- |
| **Photos**      | Inlined as a vision block it can see directly, plus a short text description for later reference.                           |
| **Documents**   | Images and PDFs come in as readable content; other files arrive as a stored file reference the agent can open.              |
| **Voice notes** | Transcribed automatically on arrival, so the transcript stands in as your message, and kept as a file it can re-transcribe. |
| **Audio files** | Stored as a file, not auto-transcribed; the agent can call `TranscribeAudio` on it when the contents matter.                |
| **Albums**      | Several photos sent together are combined into one message with every image attached.                                       |

Video isn't supported yet. A message with nothing routable—no text, caption, or supported attachment—is dropped.

### Replies and progress updates [#replies-and-progress-updates]

Replies are formatted in Telegram's MarkdownV2 so links render as tappable links. Because Telegram caps a message at 4096 characters and the platform's formatting is applied only when the escaped text fits under that cap, a very long reply falls back to plain text rather than arriving broken.

Images the agent produces through Hyperagent's own file pipeline are sent as real Telegram photos. External image URLs the agent might emit are deliberately demoted to plain links and never fetched and re-sent as photos, which closes off a way for a crafted URL to exfiltrate data or probe internal services.

With **Show progress updates** on, the bot edits a single status message in place during a run to show what the agent is doing. It's on for DMs and off for groups by default, since **Also in group chats** would double the message count in a shared room.



## Deliver scheduled and Live Mode updates [#deliver-scheduled-and-live-mode-updates]

[Live Mode](https://www.hyperagent.com/docs/concepts/agents/invocations/live-mode) and [scheduled](https://www.hyperagent.com/docs/concepts/agents/invocations/schedules) runs can deliver reports and alerts into a Telegram chat the agent already knows.

### Link the destination chat [#link-the-destination-chat]

Message the bot from the DM, group, or topic where you want updates. Hyperagent creates the chat-to-thread mapping from that first message.

### Target the linked thread [#target-the-linked-thread]

Choose that existing thread for the Live Mode or scheduled run. Delivery follows the schedule's target thread back to its Telegram chat.

### Select Telegram delivery [#select-telegram-delivery]

Choose Telegram as the delivery channel and save. Hyperagent checks the connection, pairing, and chat mapping before it lets the watch or schedule run.

A schedule that creates a new thread for every run has no Telegram chat to
deliver to. Target a thread that was created from the destination chat.



Before it lets you save, Hyperagent runs a preflight that catches the setup gaps in plain terms:

| If                                | You'll be told                                                                                                                           |
| --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| No bot is connected               | "Connect a Telegram bot for this agent before using Telegram delivery."                                                                  |
| The bot isn't paired              | "Finish pairing this agent's Telegram bot before using Telegram delivery."                                                               |
| The thread isn't linked to a chat | "The selected thread isn't linked to a Telegram chat. Message the agent's bot from the chat you want reports in, then pick that thread." |

A delivery warning appears only when the last three completed runs hit the
same problem, so one transient failure doesn't raise a false alarm. If the
token is revoked in BotFather or someone blocks the bot, Hyperagent surfaces
the matching warning and asks you to reconnect or unblock it.

## Troubleshooting and FAQs [#troubleshooting-and-faqs]

Being added to a group isn't authorization. Turn on **Allow group chats** on the bot, then send `/authorize` in the group as the paired owner. If you're on the default or the every-message trigger, also disable privacy mode in BotFather and re-add the bot, because Telegram won't forward the messages otherwise.

Check the response trigger. On the default, the bot only answers @mentions and direct replies to its own messages, and with Telegram privacy mode still on, even plain @mentions don't reach it. Either reply directly to a bot message, or disable privacy mode in BotFather and re-add the bot, or switch the trigger to every message.

They can open a chat with it, but they won't get answers. Direct messages are answered only for the paired owner. A non-owner gets a single "not configured to respond to you" notice per hour, then silence. To let others reach the agent, use it in a group with the **Anyone in the group** policy instead.

Re-pairing is for handing the bot to a different Telegram account, so it resets this bot's thread mappings on purpose. That keeps the newly paired person from inheriting the previous owner's conversations. If you only need a fresh link for the same account, generating one still rotates the token without any change of identity.

No. One bot binds to one agent, and one token binds to one bot across the whole platform. To move a bot to a different agent, connect its token there, which replaces the old binding.

Photos come in as images the agent can see. Voice notes are transcribed automatically, so you can just talk. Documents and PDFs are readable; other files and uploaded audio are stored for the agent to open or transcribe on demand. Everything is capped at 20 MB, and video isn't supported yet.