MTClaw/docs/telegram-setup.md

Telegram setup

How to create a bot, get its token, find the numeric IDs MTClaw's allowlist needs, and understand require_mention and group chat IDs. Read docs/security.md first: the bot token you are about to create is equivalent to shell access on this machine once MTClaw is configured.

1. Create the bot with BotFather

1. Open a chat with @BotFather in Telegram.

2. Send /newbot and follow the prompts: a display name, then a username ending in bot (e.g. my_mtclaw_bot).

3. BotFather replies with a token that looks like 123456789:AAExampleTokenDoNotUseThisOne. That is the value channels.telegram.token_env (or token_file) points at - never paste it into config.yaml directly; MTClaw's config loader rejects a literal token: key outright.

4. Set it as an environment variable before running mtclaw:

   export TELEGRAM_BOT_TOKEN=123456789:AAExampleTokenDoNotUseThisOne   # POSIX
   setx TELEGRAM_BOT_TOKEN "123456789:AAExampleTokenDoNotUseThisOne"   # Windows
   

mtclaw onboard walks through this same sequence interactively and calls getMe to confirm the token works before moving on.

2. /setprivacy and the re-add requirement

By default, a Telegram bot added to a group only receives messages that are commands (/something) or that explicitly mention it - this is Telegram's own "privacy mode," separate from MTClaw's own require_mention setting described below.

If you want the bot to see more of a group's messages (still gated by MTClaw's own require_mention and allowlist), talk to BotFather:

1. /mybots -> select your bot -> Bot Settings -> Group Privacy.
2. Turn privacy mode off.
3. You must remove the bot from any group it is already in and re-add it for the privacy setting change to take effect - Telegram applies privacy mode at the time the bot joins a group, not retroactively.

If you leave privacy mode on (the default), that is fine and often what you want: combined with MTClaw's require_mention: true default, the bot only ever sees messages that already mention it.

3. Finding your numeric user ID

MTClaw's allowlist (channels.telegram.allow_from) is a list of numeric Telegram user IDs, not usernames - usernames can change; numeric IDs do not.

The easiest way: run mtclaw onboard. Its interactive capture step opens a temporary long poll and tells you to message the bot; whoever messages it during that window has their username and numeric ID printed on screen, and onboard asks for explicit confirmation before writing it to allow_from.

To get your ID at any other time, once the bot is running:

• Message the bot /whoami. It replies with your numeric user ID (and the chat ID, if you sent it from a group).
• Alternatively, message any of the several public "get my Telegram ID" bots (e.g. @userinfobot) - useful before your own bot is even running yet.

4. Group and supergroup chat IDs

A regular Telegram group has a negative chat ID (e.g. -123456789). A supergroup (what a regular group becomes once it grows past a certain size, or once certain settings are enabled) has a chat ID with a -100 prefix (e.g. -1001234567890). Both forms are negative - if a chat ID you are about to write into channels.telegram.groups is positive, it is a user ID, not a group, and config.Validate rejects it with a message saying exactly that.

To key a channels.telegram.groups entry:

channels:
  telegram:
    groups:
      "-1001234567890":
        require_mention: true
        allow_from: []   # empty inherits channels.telegram.allow_from

Get a group's chat ID the same way as a user ID: send /whoami in that group once the bot is a member (privacy mode considerations from step 2 apply to whether the bot even sees the command).

5. require_mention behavior

require_mention (default true, applied via the "*" key that every group not otherwise listed inherits) controls whether the bot must be @mentioned or replied-to in a group chat before it treats a message as directed at it:

• true (default): only messages that @mention the bot, or that reply directly to one of the bot's own messages, are forwarded to the agent loop. Everything else in the group is ignored - this is what keeps a busy group chat from turning into a stream of unwanted API calls.
• false: every message from an allowed sender in that group is forwarded, mention or not. Only turn this off for a group you expect to use almost entirely for talking to the bot.

require_mention and the allowlist are independent checks - both must pass for a group message to reach the agent loop: the sender must be on the effective allowlist for that group (channels.telegram.groups.<id>.allow_from if non-empty, otherwise channels.telegram.allow_from), and the message must satisfy require_mention if it is set for that group.