Skip to main content
Connect IronClaw to a Telegram bot so your agent can receive and reply to messages in direct messages and group chats.

​
Prerequisites

  • A Telegram account
  • An IronClaw instance reachable from Telegram over HTTPS

​
Setup

1

Create a bot

Message BotFather and send /newbot. Choose a name and a username ending in bot. BotFather replies with a token that looks like 123456789:ABCdefGhIJKlmNoPQRsTUVwxyZ.
The bot token is a full credential for your bot. Anyone holding it can read and send messages as your agent. Don’t paste it into a shared channel or commit it to a repository.
2

Start IronClaw

3

Enter the bot token (operator, once per instance)

In the web interface, open Extensions, switch to the Channels tab, and scroll to the bottom of the Built-in section. Use Configure on the Telegram card and paste the bot token.
Do not use Configure on Telegram from the Registry tab. That button opens the pairing panel, which assumes the bot is already configured, so it can only fail with “An administrator must configure the Telegram bot first.” The message sounds like a permissions problem; it isn’t. Use the Channels tab.
The token is stored in the encrypted secret store, and the webhook is registered with Telegram for you. Telegram delivers updates to:
4

Pair your account (each person)

Configuring the bot does not connect you to it. Pairing is a separate step that tells IronClaw which Telegram user corresponds to which IronClaw user. Start a chat with your bot and follow the pairing prompt.Pairing is what stops a stranger who finds your bot from talking to your agent as you.
5

Talk to it

Send your bot a direct message. To use it in a group, add the bot to the group — by default Telegram bots only see messages that mention them.

​
Configuration

Telegram has no settings in config.toml and no CLI enablement key. The ingress route is compiled in and mounted unconditionally; it starts serving once you install the Telegram extension and finish bot setup in the WebUI (see the steps above). Until then it returns 503. The bot token lives in the encrypted secret store, not in config.toml. See Configuration.
A [telegram] section left over from an older release still parses, but nothing reads it — ironclaw serve logs a deprecation notice on boot. Delete the section to silence it.

​
Troubleshooting

Telegram delivers updates by webhook, so your instance must be reachable over HTTPS with a valid certificate. Telegram will not deliver to a self-signed endpoint or a private address.
Either mention the bot directly, or turn off privacy mode through BotFather (/setprivacy) so it can see all group messages.
Anyone who knows the bot’s username can start a chat with it. Unpaired users are not treated as you — complete pairing so your agent only acts on your behalf for your own account.
The instance-wide bot token has not been set, or you reached the pairing panel from the Registry tab before it was. Open Extensions → Channels, scroll to the bottom of the Built-in section, and use Configure on the Telegram card there.
The operator half — configuring the bot token — is deliberately not something the agent can do for you; follow the steps above in the web interface. Once the bot is configured, asking the agent does work for your personal half: it installs and activates the extension and surfaces the pairing panel so you can link your Telegram account.