Connect an Agent to Telegram

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

1. Open @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.

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.

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.

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.

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.

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 for the precise delivery rules.

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.

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.

Connection allowlists use numeric Telegram identifiers, not usernames.

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"
    }
  }
}

The Bot API defines getUpdates and chat identifiers in the Telegram Bot API reference.

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

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 for policy guidance.

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

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 for the full layered verification.