Platforms

On this page

Overview
Connection model
Before you begin
1. Create the Telegram bot
2. Configure Telegram privacy
3. Connect Agent Barn
4. Find Telegram IDs
5. Configure access
6. Start the Agent
7. Verify the integration
Manage the bot token
API reference
Troubleshooting
Next steps

Telegram
Hermes and OpenClaw
10–15 minutes

Connect an Agent to Telegram so people can communicate with it through direct messages or approved group conversations.

This guide walks you through creating a Telegram bot with BotFather, connecting its token to Agent Barn, defining who can reach it, and verifying the completed integration.

Overview

Every Telegram integration uses a Telegram bot account created through BotFather. Telegram provides a bot token, and Agent Barn supplies that token to the Agent runtime. Agent Barn does not create the bot for you.

When you finish this guide, you will have:

A Telegram bot created with BotFather
The bot connected to an Agent Barn Agent
Group and direct-message access policies
A verified Telegram conversation with the Agent
A plan for securely rotating the bot token

Runtime	Telegram support	Group access	Direct messages
Hermes	Supported	Open or allowlisted groups	Open, allowlisted, or off
OpenClaw	Supported	Open or allowlisted groups	Open, allowlisted, or off

Use a separate Telegram bot for each production Agent. Although a token can technically be entered in more than one configuration, multiple runtimes consuming updates for the same bot will produce unreliable behavior.

Connection model

The integration follows this path.

Telegram user or group
Telegram Bot API
Agent runtime
Agent Barn

The runtime authenticates with Telegram using the bot token and receives updates from the Telegram Bot API.

No public Telegram webhook URL is required for this Agent Barn setup. The Agent runtime establishes the outbound connection to Telegram.

Agent Barn validates a new bot token with Telegram’s getMe method before saving it. The token is then stored as an encrypted Agent secret.

Before you begin

Make sure you have:

Access to the Agent Barn organization where the Agent will be created
Permission to create an Agent
Permission to manage the Agent’s secrets and channel access
A Telegram account that can communicate with @BotFather
An available Hermes or OpenClaw runtime
Model credentials or a model provider configured for the Agent
A Telegram group where you can add the bot, if you plan to support group conversations

You do not need to make the bot a Telegram group administrator for ordinary conversations. Grant administrator permissions only if your use case specifically requires them.

Create the Telegram bot

Start the Agent creation flow

In Agent Barn:

Open the organization where you want to create the Agent.
Select Hire Agent.
Enter the Agent’s name.
Select either Hermes or OpenClaw as the runtime.
Select Telegram as the platform.

An Agent’s platform cannot be changed after creation. If you later need the same configuration on another platform, create another Agent.

Open BotFather

Open @BotFather in Telegram. BotFather is Telegram’s official interface for creating and managing bot accounts.

Send /newbot. BotFather will ask you for a display name for the bot, and then a unique Telegram username.

Telegram bot usernames are between 5 and 32 characters, may contain letters, numbers, and underscores, and normally end in bot. Choose the username carefully, because it 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.

BotFather then returns the bot token. Copy it and store it somewhere secure temporarily. Do not paste it into documentation, source control, issue trackers, or chat messages.

123456789:REDACTED_BOT_TOKEN

Anyone who obtains the token can control the bot. Telegram documents the creation process and token security requirements in its bot features documentation.

You now have a Telegram bot username and its token, ready to connect to Agent Barn.

Configure Telegram privacy

Telegram enables Group Privacy for new bots by default.

With privacy enabled, Telegram sends the bot a limited set of relevant group messages, such as commands and replies. A bot that is a group administrator or has privacy disabled can receive a broader set of group messages, excluding messages sent by other bots. See Telegram’s Bots FAQ for the precise delivery rules.

Keep privacy enabled

Use when: commands and direct replies provide enough context.

Effect: Telegram limits which group messages reach the runtime, so less group conversation leaves Telegram.

Disable privacy

Use when: the Agent needs reliable group mentions and surrounding conversation context.

Effect: Telegram sends the runtime more human-authored group messages, including messages the Agent will never answer.

To change the setting:

Send /mybots to BotFather.
Select the new bot.
Select Bot Settings.
Select Group Privacy.
Select Turn off if the Agent requires full group-message delivery.

Telegram also supports managing this through /setprivacy.

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.

Connect Agent Barn

Return to the Agent Barn hiring flow. In the Telegram connection section:

Paste the token supplied by BotFather.
Wait for Agent Barn to validate it.
Confirm that the displayed bot username matches the bot you created.
Finish the remaining runtime and model configuration.
Create the Agent.

Agent Barn validates the token against Telegram before encrypting and storing it.

The newly created Telegram Agent initially remains Stopped while you configure channel access.

If validation fails:

Confirm that the entire token was copied.
Remove leading or trailing spaces.
Make sure the token belongs to the intended bot.
Check whether the token was revoked in BotFather.
Generate a replacement token if the original can no longer be trusted.

The Agent exists in Agent Barn with a validated Telegram credential, and is waiting for its access policy.

Find Telegram IDs

Agent Barn allowlists use numeric Telegram identifiers, not usernames.

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

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

Retrieve IDs before starting the Agent

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

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

Then run:

read -s TELEGRAM_AGENT_TOKEN
curl --silent "https://api.telegram.org/bot${TELEGRAM_AGENT_TOKEN}/getUpdates"
unset TELEGRAM_AGENT_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 or chat 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.

Do not leave the token in scripts, saved terminal output, screenshots, or shell configuration.

If Telegram converts a group into a supergroup, its chat ID may change. Update the Agent’s allowlist with the new ID.

Configure access

In the final Telegram setup panel, open Chats & endpoint, then review both boundaries.

Group access

Allowlist Recommended The Agent responds only in the listed group chats.
Open The Agent can respond when addressed in any group containing the bot. Suitable for controlled development environments.
No approved chats Group use is not exposed as a separate off switch in every configuration flow. Omit all approved chats for an Agent intended only for direct use.

Direct-message access

Off Recommended The Agent ignores direct messages. Use this when the Agent is group-only.
Allowlist Recommended Only users with listed Telegram user IDs can message it.
Open Any Telegram user who finds the bot can message it. Use only for public-facing bots.

For a group Allowlist, enter the numeric Telegram chat IDs as a comma-separated list:

-1001234567890, -1009876543210

Open access does not add the bot to groups automatically. A Telegram user must still add the bot to each group.

The runtime requires an explicit mention in group conversations. For example:

@agent_barn_support_bot summarize the decisions in this thread

A direct reply to a message sent by the Agent may also reach it without repeating the username.

For a direct-message Allowlist, enter numeric Telegram user IDs:

123456789, 987654321

Telegram bots cannot begin a private conversation with a user. The user must first open the bot and send a message such as /start. This is part of Telegram’s bot interaction model.

Hermes home chat

Hermes can use the first allowed Telegram chat ID as its home destination for scheduled or proactive delivery. If Hermes should send scheduled messages:

Use the Allowlist group policy.
Put the intended home group first in Allowed chat IDs.
Make sure the bot is a member of that group.
Make sure it has permission to post messages.

Without an allowed chat ID, Hermes has no default Telegram destination for proactive messages.

Start the Agent

After reviewing the Telegram policies:

Select Save & Start.
Wait for the Agent to move from Stopped to Initializing.
Wait for it to reach Running.

Agent Barn validates the bot token again while starting the runtime. If Telegram rejects the token, the Agent may enter Error rather than Running.

If you close the setup panel without saving, the Agent remains stopped.

The Agent reports Running, and its runtime is polling Telegram for updates.

Verify the integration

Test both successful and rejected cases. A production verification should prove that the Agent responds where expected, and remains silent everywhere else.

Test	Action	Expected result
Allowed group mention	Mention the bot in an allowed group	Agent responds
Unmentioned group message	Send an ordinary message without addressing the bot	Agent does not respond
Disallowed group	Add or test the bot in a group not on the allowlist	Agent does not respond
Allowed direct message	An allowed user sends `/start` and a message	Agent responds
Disallowed direct message	A user outside the allowlist sends a message	Agent does not respond

A suitable group test is:

@agent_barn_support_bot reply with "Telegram connection verified"

Then verify in Agent Barn:

The Agent remains Running.
The conversation appears in the Agent’s activity.
The inbound message has the expected Telegram chat or user context.
The Agent’s response appears in Telegram.
No unexpected error appears in the Agent logs.

A Telegram delivery can succeed even if the model later fails. If the inbound message appears in Agent Barn but there is no useful response, check model credentials and runtime logs separately from the Telegram connection.

Manage the bot token

Do not:

Commit it to the agent-barn repository.
Put it in an environment example containing real values.
Share it in screenshots or support conversations.
Reuse it across production Agents.
Leave it in shell history.
Expose it in browser URLs, logs, or monitoring labels.

To rotate a compromised token:

Open @BotFather.
Send /mybots.
Select the affected bot.
Open API Token.
Revoke the old token and generate a new one.
Open the Agent in Agent Barn.
Update the Telegram token under Keys & integrations.
Select Apply & Restart if the Agent is running.
Verify the integration again.

Revoking a token immediately prevents the old token from authenticating. The Agent will not reconnect until its saved credential is replaced.

Changing channel access and changing the bot token are separate operations:

Channel policies require permission to update the Agent.
Bot-token changes require permission to manage Agent secrets.

API reference

You can also create a Telegram Agent through the Agent Barn API.

Method and endpoint	Purpose
`POST /organizations/{organization_id}/agents`	Create the Telegram Agent in a stopped state
`POST /agents/{agent_id}/start`	Start the Agent after checking the saved policy
`PUT /agents/{agent_id}`	Update the access policy or the bot token

 Create the Agent
   Create Agent request  
 {
  "name": "Telegram Support Agent",
  "platform": "telegram",
  "agent_type": "hermes",
  "telegram_bot_token": "REDACTED",
  "telegram_group_policy": "allowlist",
  "telegram_dm_policy": "off",
  "telegram_allowed_chat_ids": [
    "-1001234567890"
  ],
  "telegram_allowed_user_ids": [],
  "model": "REPLACE_WITH_MODEL",
  "template_key": "REPLACE_WITH_TEMPLATE",
  "skills": []
}
 
  The API creates the Agent in a stopped state. Start it explicitly after checking the saved policy.
 Update the Agent
 Example access-policy update:
   Update access policy  
 {
  "telegram_group_policy": "allowlist",
  "telegram_dm_policy": "allowlist",
  "telegram_allowed_chat_ids": [
    "-1001234567890",
    "-1009876543210"
  ],
  "telegram_allowed_user_ids": [
    "123456789"
  ]
}
 
  Example token update:
   Update bot token  
 {
  "telegram_bot_token": "REDACTED"
}
 
  After updating credentials for a running Agent, restart it so the runtime receives the new secret.
 Telegram fields
     Field  Purpose  
 
  platform Must be telegram
 telegram_bot_token Token issued by BotFather
 telegram_group_policy open or allowlist
 telegram_dm_policy off, open, or allowlist
 telegram_allowed_chat_ids Numeric group or chat IDs stored as strings
 telegram_allowed_user_ids Numeric Telegram user IDs stored as strings
 
 
 
 Never include a real token in API examples, logs, or stored request fixtures.

  Troubleshooting
   Agent Barn says the token is invalid
 Validation runs against Telegram 
   Copy the token directly from BotFather again.
 Check for spaces or missing characters.
 Confirm that the token belongs to the intended bot.
 Make sure it has not been revoked.
 Generate a new token through BotFather if necessary.
 Confirm that the Agent Barn host can reach api.telegram.org.
 
 
 
   The Agent does not receive group messages
 Membership, allowlist, or privacy 
  Check that:
  The bot has been added to the group.
 The Agent is Running.
 The group is on the Agent’s allowlist.
 The message explicitly mentions the bot, or directly replies to it.
 Telegram Group Privacy matches your intended delivery behavior.
 The bot was removed and added again after changing Group Privacy.
 No other runtime is consuming updates for the same bot.
 
 
 
   The Agent receives commands but not ordinary mentions
 Group Privacy is filtering updates 
  Telegram Group Privacy may be limiting the updates delivered to the runtime.
 Use BotFather to disable Group Privacy, remove the bot from the group, and add it again. Remember that this allows the runtime to receive more messages from the group, even though Agent Barn still applies mention gating.
 
 
   Direct messages do not work
 Policy or identifier mismatch 
   Confirm that direct messages are Open or Allowlist.
 If using an allowlist, check message.from.id, not message.chat.id from a group update.
 Ask the user to open the bot and send /start.
 Confirm that the user has not blocked the bot.
 Review the Agent logs for policy rejections.
 
 
 
   The group allowlist does not work
 Chat IDs are numeric and can change 
   Use the numeric message.chat.id, not the group name.
 Keep the leading minus sign.
 Store the ID as a string when using the API.
 If the group became a supergroup, retrieve and save its new ID.
 Apply the updated policy and restart the Agent if prompted.
 
 
 
   getUpdates returns no results
 Another consumer or a webhook 
   Send the bot a new targeted message or command.
 Confirm that the token belongs to the correct bot.
 Stop the Agent temporarily so it is not consuming the updates first.
 Stop any other service using long polling for the same bot.
 Check whether the bot has a webhook configured.
 Confirm that Telegram Group Privacy permits the test message to reach the bot.
 
 Do not leave a manual getUpdates process running after starting the Agent.
 
 
   The Agent enters Error during startup
 Credential or connectivity failure 
   Revalidate the token with BotFather.
 Confirm that the token was not rotated after it was saved.
 Check outbound network access to Telegram.
 Review the Agent’s startup logs.
 Replace the token and apply the configuration again.
 Confirm that the selected runtime supports Telegram.
 
 
 
   The Agent receives messages but does not answer
 Delivery succeeded, processing failed 
  This normally means Telegram delivery succeeded but processing failed. Check:
  Model credentials.
 Model availability.
 Runtime logs.
 Agent configuration.
 Tool or skill errors.
 Provider rate limits.
 Whether the Agent is still Running.
 
 
 
   A scheduled Hermes message is not delivered
 No usable home destination 
   Confirm that the Agent uses Hermes.
 Add at least one allowed Telegram chat ID.
 Put the intended destination first in the list.
 Confirm that the bot is still a member of that chat.
 Confirm that the bot can post messages.
 Restart the Agent after changing the destination.
 
 
 
   Responses appear inconsistently
 Two consumers share one bot 
  Make sure the Telegram token is not being used by:
  Another Agent.
 A development runtime.
 A local polling script.
 A previous deployment.
 An external automation service.
 
 Only one Agent runtime should consume updates for a Telegram bot.
 
 
 
  Next steps
 After the Telegram integration is verified:
  Review the Agent’s health and logs
 Refine the group and direct-message allowlists
 Configure the Agent’s model, instructions, tools, and Skills
 Test access with a user who should be denied
 Document who owns the Telegram bot and the token-rotation process
 Set up Discord, if the Agent also needs to operate there

Field	Purpose
`platform`	Must be `telegram`
`telegram_bot_token`	Token issued by BotFather
`telegram_group_policy`	`open` or `allowlist`
`telegram_dm_policy`	`off`, `open`, or `allowlist`
`telegram_allowed_chat_ids`	Numeric group or chat IDs stored as strings
`telegram_allowed_user_ids`	Numeric Telegram user IDs stored as strings

Set up Telegram

Overview

Connection model

Before you begin

Create the Telegram bot

Start the Agent creation flow

Open BotFather

Configure Telegram privacy

Keep privacy enabled

Disable privacy

Connect Agent Barn

Find Telegram IDs

Retrieve IDs before starting the Agent

Configure access

Group access

Direct-message access

Hermes home chat

Start the Agent

Verify the integration

Manage the bot token

API reference

Create the Agent

Update the Agent

Telegram fields

Troubleshooting

Agent Barn says the token is invalid

The Agent does not receive group messages

The Agent receives commands but not ordinary mentions

Direct messages do not work

The group allowlist does not work

`getUpdates` returns no results

The Agent enters Error during startup

The Agent receives messages but does not answer

A scheduled Hermes message is not delivered

Responses appear inconsistently

Next steps