---
title: Connect an Agent to Telegram
canonical: "https://agentbarn.dev/guides/platforms/telegram"
pubDate: "2026-08-29T00:00:00.000Z"
updatedDate: "2026-09-13T13:41:42.000Z"
author: Agent Barn
description: "Connect Telegram to an Agent Barn Agent: create a bot with BotFather, add its token to a polling-based Communication Connection, and set group and direct-message policy."
tags: [Platforms, How-to, "Telegram administrators, Agent creators, organization administrators, and Agent operators", Telegram, BotFather, bot token, Communication Connection, getUpdates polling, privacy mode, group access, direct messages, chat ID, user ID]
categories: [Guides, Platforms]
---

-   Telegram
-   Hermes and OpenClaw
-   10–15 minutes

Connect Telegram to an existing Agent by creating a Telegram Communication Connection. You create a bot with BotFather, paste its token into the Connection, and choose which groups and users may reach the Agent.

Telegram works with both Hermes and OpenClaw. Agent Barn's Communications Gateway supervises Telegram polling, so no public webhook is required.

## Overview

Telegram is not selected while creating the Agent. The Agent is created headless, and Telegram is added afterward as a Connection.

-   An Agent can have zero or many Communication Connections.
-   The same Agent can have multiple Telegram Connections using different bots.
-   The Communications Gateway supervises the Telegram polling loop.
-   The Runtime never receives the Telegram bot token and does not own the polling loop.
-   A public Telegram webhook is not required.

When you finish this guide, you will have:

-   A Telegram bot created with BotFather
-   A Telegram Communication Connection on an existing Agent
-   Group and direct-message policies for that Connection
-   A verified Telegram conversation with the Agent
-   A plan for rotating the bot token through the Connection

See [Communication Connections](/guides/agents/communication-connections) for the shared Connection lifecycle, and [Compare platform compatibility](/guides/platforms/compatibility) for how Telegram sits beside the other Platforms.

## Connection model

The Telegram Platform Plugin uses `getUpdates` long polling, held by the Communications Gateway:

1.  Telegram user, group, or channel
2.  Telegram Bot API
3.  Supervised getUpdates polling
4.  Communications Gateway
5.  Hermes or OpenClaw

Replies return through the same Connection, sent by the Gateway with the Connection's own bot token. The Runtime receives only normalized Communication Deliveries.

**Important**

Do not configure a Telegram webhook. Telegram treats polling and webhooks as mutually exclusive, and this Connection uses polling.

## Before you begin

You need:

-   An existing Agent
-   Permission to update the Agent and manage its Connection credentials
-   A Telegram account that can interact with `@BotFather`
-   Permission to add the resulting bot to the intended groups or channels
-   A Telegram bot token in the `<bot-id>:<secret>` format

**Security**

Anyone who obtains the bot token can control the bot. Never commit it, paste it into a Template or Skill, or send it through a chat message. Enter it only into the Connection credential field.

## Create the Telegram bot

Open [`@BotFather`](https://t.me/BotFather) in Telegram. BotFather is Telegram's official interface for creating and managing bot accounts.

1.  Open [@BotFather](https://t.me/BotFather).
2.  Run `/newbot`.
3.  Choose the bot's display name.
4.  Choose its Telegram username.
5.  Copy the bot token returned by BotFather.
6.  Confirm that the token resembles `<bot-id>:<secret>`.

Telegram bot usernames are between 5 and 32 characters, may contain letters, numbers, and underscores, and normally end in `bot`. Choose carefully, because the username becomes the public identity people use to find and mention the bot.

BotFather /newbot

You:       /newbot
BotFather: All right, a new bot. How are we going to call it?
You:       Support Agent
BotFather: Good. Now let's choose a username for your bot.
You:       agent\_barn\_support\_bot

This is an illustration of the exchange, not a screenshot.

```
123456789:REDACTED_BOT_TOKEN
```

About this credential:

-   The bot token is the only provider credential required by this Connection.
-   The bot username is not a credential, and must not be entered in place of the token.
-   Telegram does not require a separate app token or OAuth credential for this Connection.
-   The token must be kept private.

Telegram documents the creation process and token security requirements in its [bot features documentation](https://core.telegram.org/bots/features).

## Prepare the bot for polling

A Telegram bot can have only one effective update consumer. Before creating the Connection:

-   Remove any webhook currently configured for the bot
-   Stop any other application or process polling the same bot token
-   Confirm the bot token is not already used by another active Communication Connection

Agent Barn enforces global credential uniqueness for the bot token, which prevents two Connections from competing for the same bot's updates.

**Warning**

If another poller keeps running, updates are split unpredictably between consumers and the Agent will appear to miss messages at random.

## Create the Telegram Connection

With the token in hand, create the Connection on the Agent.

1.  Open the existing Agent.
2.  Open its **Communication Connections** section.
3.  Choose Telegram.
4.  Enter a Connection display name.
5.  Paste the BotFather token into **Bot token**.
6.  Configure group and direct-message access.
7.  Create and enable the Connection.

Use a display name that identifies the bot or purpose, such as `Telegram: Incident bot`.

**Security**

The credential belongs to the Communication Connection. It is encrypted at rest, the stored token is not returned through the API, and it is never materialized into Hermes or OpenClaw.

The Communications Gateway validates the bot token with Telegram and supervises its polling lifecycle. If validation fails, confirm that the entire token was copied, remove leading or trailing spaces, check that the token belongs to the intended bot, and generate a replacement in BotFather if the original can no longer be trusted.

## Add the bot to groups and set privacy

Telegram decides which group messages reach a bot at all, before Agent Barn sees them.

1.  Add the bot to every Telegram group or supergroup it should serve.
2.  Open `@BotFather`.
3.  Run `/setprivacy`.
4.  Select the bot.
5.  Disable privacy mode when the Agent must receive ordinary group messages.

Telegram enables Group Privacy for new bots by default. With privacy enabled, Telegram delivers only a limited set of group messages, generally favoring commands, replies, and mentions. Disabling it delivers a broader set of human-authored group messages. See Telegram's [Bots FAQ](https://core.telegram.org/bots/faq) for the precise delivery rules.

### Keep privacy enabled

**Use when:** commands, replies, and mentions provide enough context.

**Effect:** Telegram limits which group messages leave Telegram at all.

### Disable privacy

**Use when:** the Agent needs reliable delivery of ordinary group conversation.

**Effect:** Telegram delivers more group messages, including messages the Agent will never answer.

**Important**

Privacy mode is a Telegram-side delivery setting, not an Agent Barn policy. It runs before Agent Barn receives the message. Access authorization is separate and belongs to the Connection's group and direct-message policies.

If you change Group Privacy after adding the bot to a group, remove the bot and add it again so Telegram applies the new setting. This requirement is documented in Telegram's [bot feature guide](https://core.telegram.org/bots/features#privacy-mode).

## Add the bot to channels

For Telegram channels:

-   The bot must be added to the channel.
-   The bot should be made a channel administrator when it needs to receive channel posts and send replies.
-   Channel access still remains subject to the Communication Connection's group policy.

Adding the bot does not authorize every channel. Presence in Telegram and admission in Agent Barn are two separate gates, and an `allowlist` policy still needs the channel's ID.

## Find Telegram IDs

Connection allowlists use numeric Telegram identifiers, not usernames.

| Identifier | Used for | Typical format |
| --- | --- | --- |
| Group, supergroup, or channel ID | Group allowlist | Negative number, often beginning with `-100` for a supergroup |
| User ID | Direct-message allowlist | Positive number |
| Bot username | Mentions and discovery, never access control | `@agent_barn_support_bot` |

Telegram chat IDs are stable numeric identifiers. Group names and user display names are not access-control identifiers and cannot be entered in an allowlist.

### Retrieve IDs before enabling the Connection

You can inspect updates received by the bot using Telegram's `getUpdates` method. First:

1.  Add the bot to the intended Telegram group.
2.  Send a command, direct reply, or message addressed to the bot.
3.  If you need a user ID, send the bot a direct message as that user.

Then run:

```
read -s TELEGRAM_BOT_TOKEN
curl --silent "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/getUpdates"
unset TELEGRAM_BOT_TOKEN
```

When prompted by `read`, paste the bot token and press Enter. The token is not displayed, and its value is not included in the command history.

Inspect the response for fields similar to:

```
{
  "message": {
    "from": {
      "id": 123456789
    },
    "chat": {
      "id": -1001234567890,
      "title": "Engineering"
    }
  }
}
```

**Response field mapping**

`message.chat.id`

`allowed_chat_ids`: the group allowlist

`message.from.id`

`allowed_user_ids`: the direct-message allowlist

The Bot API defines `getUpdates` and chat identifiers in the [Telegram Bot API reference](https://core.telegram.org/bots/api#getupdates).

**Warning**

Only one long-polling consumer may retrieve updates for a bot at a time. Do this before the Connection is enabled, or disable the Connection while you run `getUpdates`, so you are not competing with its supervised poller.

## Configure the Connection settings

The Telegram Platform Plugin supplies these settings on the Connection form.

| Setting | Behavior | Underlying setting |
| --- | --- | --- |
| Group access | open: accept eligible messages from any group, supergroup, or channel where the bot is present; allowlist: accept messages only from configured Telegram chat IDs | `group_policy` |
| Allowed groups | Telegram group, supergroup, or channel IDs, used when Group access is allowlist | `allowed_chat_ids` |
| Direct messages | off: ignore private chats; open: accept private messages from any Telegram user; allowlist: accept private messages only from configured users | `dm_policy` |
| Allowed DM senders | Numeric Telegram user IDs, used when Direct messages is allowlist | `allowed_user_ids` |

When entering identifiers:

-   Use numeric Telegram IDs, not usernames.
-   Group and supergroup IDs are often negative.
-   Preserve IDs exactly as Telegram supplies them, including the leading minus sign.
-   A username such as `@example` is not a substitute for a numeric user ID.

Start with one allowed group and direct messages off, then widen after the first successful exchange. See [Configure channel access](/guides/agents/channel-access) for policy guidance.

**Warning**

An allowlist never adds the bot anywhere. Telegram group and channel membership still applies, and `open` only permits messages from chats where the bot is already present.

## Verify the integration

Confirm the Connection is enabled and its poller is healthy, then test from a controlled chat.

| Test | Expected result |
| --- | --- |
| Address the Agent in an allowed group | The Agent responds |
| Send a message from a group outside the allowlist | The Agent does not respond |
| Send a private message while Direct messages is `off` | The Agent does not respond |
| Send a private message as an allowed user while Direct messages is `allowlist` | The Agent responds |

Then confirm the exchange in Agent Barn:

1.  Open the Agent.
2.  Open **Conversations**.
3.  Select this Telegram Connection.
4.  Confirm the inbound message and outbound response appear under it.

See [Verify your Agent](/guides/get-started/verify-agent) for the full layered verification.

## How messages are admitted

Telegram visibility and Agent Barn authorization are two separate gates:

-   Telegram determines which group messages reach the bot at all, through its privacy mode.
-   Messages that reach Agent Barn are then evaluated against the Connection's group or direct-message policy.
-   Bot-authored messages are ignored.
-   Direct messages do not require mentions, but must pass the direct-message policy.
-   Telegram does not expose Slack's `every_message` or `start_only` thread mention setting.

So a message can be withheld by Telegram, or delivered by Telegram and then rejected by Connection policy. The Connection journal distinguishes the two.

## Topics, replies, and conversations

-   Telegram message replies are preserved as reply relationships where provider data is available.
-   Telegram forum topics are represented using the provider's message thread ID.
-   Conversations and message history remain scoped to the Telegram Connection.

The same Agent can use other Telegram bots or other Platforms without sharing provider credentials or conversation histories between Connections.

## Display-name enrichment

Agent Barn may use credential-scoped Telegram lookups to fill missing chat or sender display names.

-   Provider-supplied names are preferred.
-   Name enrichment is best-effort.
-   A lookup failure does not reject an otherwise valid message.
-   Telegram IDs remain the stable policy and conversation identifiers.
-   Cached lookups remain isolated by bot credential.

This is not a browsable directory. Telegram does not offer the Connection directory-selection experience that Slack and Discord provide, so allowlists are built from IDs you collect yourself.

## Change the Connection later

Telegram settings and credentials can be changed at any time without touching the Agent.

-   Connection updates increment the Connection revision.
-   The Communications Gateway reconciles the supervised Telegram poller independently.
-   Updating the Connection does not rebuild or restart the Agent Runtime.
-   Retiring or disabling the Connection stops its provider activity without deleting the Agent.

Rotate the credential by updating the Connection with the new BotFather token. There is no need to recreate the Agent.

## Manage the bot token

The token lives in two places: BotFather, and the Connection's credential field.

1.  Generate the replacement token in BotFather.
2.  Open the Agent's Telegram Connection.
3.  Enter the new token.
4.  Save the Connection.

The Gateway validates the new token and reconciles the poller on the next revision. Replacing a token requires Agent secret-management permission.

**Security**

Revoking a token in BotFather immediately stops the Connection's poller. Prepare the replacement first, then update the Connection.

**Important**

The Telegram Communication Connection provides message transport. Its bot token is not an Agent Secret or Shared Credential, Connection credentials are never materialized into the Agent Runtime, and adding the Connection does not grant unrelated tool Integration access.

## Troubleshooting

Start at the saved Connection's health and diagnostics, then work through these checks:

-   The bot token came from BotFather and is still valid
-   No Telegram webhook is configured for the bot
-   No other process is polling the same token
-   The bot has been added to the intended group or channel
-   Privacy mode is disabled when ordinary group messages are required
-   The bot has the necessary channel administrator access
-   The group chat ID passes the configured group policy
-   The sender ID passes the configured direct-message policy
-   The Connection is enabled and its poller is healthy

The Connection journal shows whether an update was observed, rejected by policy, delivered, retried, or dead-lettered. Use it to decide which layer to investigate.

### The bot token is rejected

Confirm the full `<bot-id>:<secret>` value was copied with no surrounding whitespace, that it belongs to the intended bot, and that it was not revoked in BotFather. Generate a replacement token if needed, then update the Connection.

Also confirm the token is not already held by another active Connection.

### No updates arrive at all

Check whether a webhook is configured for the bot, or whether another process is polling the same token. Telegram allows only one effective update consumer, and a configured webhook prevents polling entirely.

If the journal shows nothing observed, the problem is on the Telegram side or in the poller, not in the Agent.

### The Agent does not receive ordinary group messages

This is usually Telegram privacy mode. Disable Group Privacy in BotFather, then remove the bot from the group and add it again so Telegram applies the new setting.

If privacy is already disabled, check the group policy and the allowed chat IDs, including the leading minus sign.

### Direct messages do not work

Check the direct-message policy. When it is `allowlist`, confirm the sender's numeric user ID is listed; a username is not a substitute. When it is `off`, private chats are ignored by design.

### The group allowlist does not match

Re-read the chat ID from a `getUpdates` response and compare it exactly. Supergroup IDs are negative and often begin with `-100`, and a group that is upgraded to a supergroup receives a new ID.

### Responses appear inconsistently

Two consumers are usually competing for the same bot's updates. Stop any other poller, including a local `getUpdates` loop or a second Connection using the same token.

### Messages are delivered but the Agent does not answer

Admission succeeded, so the problem is downstream. Review [Agent health and logs](/guides/agents/health-and-logs) for the Runtime, then review the Connection's delivery diagnostics for the outbound reply.

Do not restart the Agent for a provider or policy problem.

**Note**

Provider polling health, admission, and delivery belong to the Connection. Agent Runtime health is a separate concern, and a message can be polled successfully but still fail later during Runtime processing or outbound delivery.

## Next steps

After the Telegram Connection is working:

-   [Review the Connection lifecycle](/guides/agents/communication-connections)
-   [Configure channel access](/guides/agents/channel-access)
-   [Verify your Agent](/guides/get-started/verify-agent)
-   [Review Agent health and logs](/guides/agents/health-and-logs), separately from Connection health
-   [Compare platform compatibility](/guides/platforms/compatibility) before adding another Connection
-   [Set up Discord](/guides/platforms/discord)