← Back to home
Bot setup · Telegram中文

Telegram Bot Setup

AgEnD talks to you through a Telegram bot in a Forum-mode group: each agent instance gets its own Topic. This guide walks you through creating the bot, preparing the group, and getting the Bot Token agend quickstart asks for. Quickstart finds the group and your User ID itself when you send /start in the group. Takes about 5 minutes.

What you'll end up with
  • • A bot token like 123456789:ABCdefGHIjklMNOpqrsTUVwxyz
  • • A private group with Topics enabled, with your bot as an admin
  • • Your numeric Telegram User ID, which quickstart reads from your /start and uses to lock the bot to you

Step-by-step

1

Create the bot with BotFather

  1. In Telegram, search for @BotFather and open a chat.
  2. Send /newbot.
  3. Enter a display name, then a username — it must end with bot.
  4. BotFather replies with your Bot Token. Keep it somewhere safe.
AGEND_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrsTUVwxyz

You don't need to set this by hand — agend quickstart prompts for it and writes it to ~/.agend/.env. Treat the token like a password: anyone who has it controls your bot.

2

Turn off Group Privacy

By default a bot only receives messages starting with / or messages that @mention it. AgEnD needs to read everything you type, so privacy mode must be off.

  1. Send /mybots to BotFather.
  2. Pick your bot → Bot Settings → Group Privacy.
  3. Choose Turn off.
BotFather Bot Settings menu with Group Privacy highlighted
Bot Settings → Group Privacy
BotFather confirming that privacy mode is disabled for the bot
Confirmation: privacy mode is disabled
3

Create a group and enable Topics

  1. Create a new group in Telegram (a private one, just for you and the bot).
  2. Open the group settings by tapping the group name.
  3. Tap Edit (the pencil icon).
  4. Turn on Topics. Each conversation now lives in its own Topic — that's how AgEnD separates instances.
Topics require a supergroup. Telegram usually upgrades a group automatically. If the Topics switch isn't there, set the group to Public once and then back to Private — that forces the upgrade.
4

Add the bot to the group as an admin

  1. In the group, tap Add Members and search for your bot's username.
  2. Group settings → Administrators → Add Admin.
  3. Select your bot and grant the permissions below.
PermissionRequired?Why
Manage TopicsRequiredCreate and manage the per-instance Topics
Send MessagesRequiredReply inside Topics
Edit MessagesRequiredLive progress updates on sent messages
Delete MessagesRecommendedHousekeeping / cleaning up noise
Pin MessagesOptionalPin important messages
The bot must be an admin with Manage Topics — otherwise it cannot create new Topics and new instances will silently fail to appear.
5

Get your User ID

Your User ID is what locks the bot down to you. It goes into fleet.yaml under access control: without an access list, anyone who finds your bot could drive your agents. Quickstart takes yours from the /start you send in the group, so you only need to look it up to check it, or to add a teammate later.

  1. Search for @userinfobot in Telegram.
  2. Send it any message.
  3. It replies with your User ID — a plain number.
Searching for @userinfobot in the Telegram search bar
Search for @userinfobot

agend quickstart writes it out for you:

channel:
  access:
    mode: locked
    allowed_users:
      - '951494522'    # your user ID

Add more IDs to the list if you want to share the fleet with teammates.

6

Run quickstart

agend quickstart      # pick Telegram, paste the token, then send /start in the group

Quickstart waits for your /start in the group and takes the group and your User ID from it. At the end it offers to install the fleet as a service and start it. If you said no, runagend start.

Then send a message in the group's General topic. If the bot answers, you're done — start adding project instances from there. To open the web dashboard, send /web in General: the bot sends you a sign-in link and a one-time code privately (open a private chat with the bot first).

Troubleshooting

SymptomCauseFix
Bot doesn't replyBot isn't an adminGroup settings → Administrators → add the bot
New Topics aren't createdMissing Manage TopicsEdit the bot's admin rights and enable Manage Topics
Bot receives nothingGroup Privacy still onBotFather → /mybots → Bot Settings → Group Privacy → Turn off
Wrong group ID formatTruncated IDSupergroup IDs start with -100, e.g. -1001234567890
Quickstart says another process is already reading this bot's updatesA running AgEnD, or a second quickstart, uses the same tokenStop it (agend stop) and run quickstart again
A teammate can't use the botOnly one user allowedAdd their user ID to allowed_users
Prefer Discord? See the Discord bot setup guide. On Windows, the Windows installation guide covers the rest.