Telegram

Interact with your agent through Telegram

In this guide, we will show you how to set up a Telegram channel to interact with your IronClaw agent. We assume that you already have an agent up and running.

If you haven’t set up your agent yet, follow our Quickstart guide

---

Set up a Telegram channel

1. Create a new bot with BotFather

   In order to create a new Telegram bot, you need to talk to BotFather, the official Telegram bot that helps you create and manage your bots.
2. Configure the Telegram channel in IronClaw

   Invoke the IronClaw CLI onboard wizard using the --channels-only flag to configure only the channels without going through the entire onboarding process again:

   ironclaw onboard --channels-only
   
3. Test your Telegram channel

   Now that you have configured your Telegram channel, it is time to test it out. Start the ironclaw agent if it is not already running:

   ironclaw
   

   Send a message to your bot in Telegram. It will respond with a command that you will need to execute in the terminal to complete the channel setup:

   ironclaw pairing approve telegram <PAIRING_CODE>
   

---

Telegram Side Settings

Privacy mode and group visibility

Telegram bots default to Privacy Mode, which limits what group messages they receive.If the bot must see all group messages, either:

• disable privacy mode via /setprivacy, or
• make the bot a group admin.

When toggling privacy mode, remove and re-add the bot in each group so Telegram applies the change.

Group permissions

Admin status is controlled in Telegram group settings.Admin bots receive all group messages, which is useful for always-on group behavior.

Helpful BotFather toggles

• /setjoingroups to allow/deny group adds
• /setprivacy for group visibility behavior

---

Configuration Options

You can configure the behavior of the Telegram channel through the .ironclaw/channels/telegram.capabilities.json file, which is created automatically after you set up the channel for the first time.

Options Overview

Option	Values	Default	Description
dm_policy	open, allowlist, pairing	pairing	Controls who can send direct messages to the bot
allow_from	user IDs	[]	Users allowed to DM the bot when dm_policy is set to allowlist
owner_id	Telegram user ID	—	If set, only this user can interact with the bot (DMs and group messages)
respond_to_all_group_messages	bool	false	Respond to all group messages
bot_username	username	—	For group mention detection whenever respond_to_all_group_messages is false
polling_enabled	bool	false	Use polling instead of webhooks
poll_interval_ms	number	30000	Polling interval in milliseconds (only used if polling_enabled is true)

Remember to restart your agent after changing the configuration file for the changes to take effect

Direct Message Policy

The dm_policy option controls who can send direct messages to the bot:

• open: anyone can DM the bot without restrictions
• allowlist: only users in the allow_from list can DM the bot
• pairing (default): the bot will DM back any user that contacts it with a pairing command that needs to be executed in the terminal

Related options:

• The allow_from option is a list of Telegram user IDs that are allowed to DM the bot when dm_policy is set to allowlist.
• The owner_id option restricts the bot to answer only messages from a specific Telegram user ID

User ID

Message @userinfobot to get your Telegram user ID.

Respond to all group messages

By default, the Telegram channel will only respond to messages that mention the bot in groups. If you want the bot to respond to all group messages, set the respond_to_all_group_messages

Relevant options:

• If respond_to_all_group_messages is set to false, the bot will only respond to messages that mention it. In this case, make sure to set the bot_username option with the bot’s username (without the @)

Polling

In case you do not want to configure a tunnel, you can setup the Telegram channel to poll for new messages every certain interval of time.

To do this, set the polling_enabled option to true and configure the poll_interval_ms option with the desired polling interval in milliseconds (default is 30000ms, which is 30 seconds).

Configuration Examples

Private Team Assistant — mentions only, pairing for DMs:

{
  "bot_username": "TeamBot",
  "respond_to_all_group_messages": false,
  "dm_policy": "pairing"
}

Always-On Expert — responds to all messages:

{
  "bot_username": "DevOpsBot",
  "respond_to_all_group_messages": true,
  "allow_from": ["*"]
}

Owner-Only — personal assistant in shared groups:

{
  "bot_username": "MyBot",
  "respond_to_all_group_messages": false,
  "owner_id": "12345678"
}

---

Group Chat Participation

IronClaw can be configured to participate in Telegram group chats, by default the bot will only respond to commands (use /help to see the list of available commands). If you want the bot to respond to mentions or all messages in a group you need to configure it.

Adding the Bot to Groups

1. Enable group privacy in @BotFather:

   • Message @BotFather
   • Send /mybots → Select your bot
   • Click “Bot Settings” → “Group Privacy”
   • Turn OFF “Privacy mode” (allows bot to see all messages)

2. Add bot to a group:

   • Open the group in Telegram
   • Add member → Search for your bot username
   • Grant admin permissions (optional but recommended)

3. Configure bot_username in IronClaw:

   {
     "bot_username": "MyIronClawBot"
   }
   

Group Trigger Modes

Commands & Mentions

The bot responds when a command is used, e.g. /skills, or when the bot is mentioned, e.g. @MyIronClawBot what's the weather?

Configuration:

• Set “Privacy mode” to OFF in @BotFather, or make the bot a group admin
• Configure the bot_username:

{
  "bot_username": "MyIronClawBot",
  "respond_to_all_group_messages": false
}

Benefits:

• Respects group conversation flow
• No spam from unsolicited responses
• Users explicitly choose to engage the agent

Respond to All Messages

The bot processes and responds to every message in the group.

• Set “Privacy mode” to OFF in @BotFather, or make the bot a group admin
• Configure both bot_username and respond_to_all_group_messages:

Configuration:

{
  "bot_username": "MyIronClawBot",
  "respond_to_all_group_messages": true
}

Use cases:

• Small team rooms where the agent is always helpful
• Automated moderation or summarization
• Specific-topic groups where the agent provides expertise

---

Message Privacy

What the bot can see

• All messages in groups where privacy mode is disabled
• Usernames and display names
• Message timestamps
• Reply chains (threading context)

What gets sent to the LLM

• The message text (with @mention stripped)
• Sender identifier (username or first name)
• Recent conversation history in that thread