Docs / Integrations / Telegram

Connect Telegram

Connect your Stand to Telegram so you can DM it from your phone, watch, or anywhere Telegram works. About 90 seconds — no dev portal, no OAuth dance.

✦ Tip: you don't have to do this alone. In AG2 Space, start a voice session with your agent, share your screen, and say "guide me through this" — it will read the page with you and narrate each step in real time.

Before you start

  • A Telegram account. If you don't have one yet, install Telegram from your phone's app store or telegram.org/apps.
  • AG2 Space installed and signed in. If not, grab it from desktop.ag2.space.

Notably absent: no developer portal, no app registration, no OAuth scopes to choose, no Telegram group or channel to create. Telegram makes the bot-creation flow remarkably short by routing everything through one in-Telegram conversation with @BotFather.

1

Start a chat with BotFather

Open Telegram and search for BotFather in the search bar at the top. Tap the result with the blue verified checkmark (@BotFather — Telegram's official bot-creation bot). The other results below it are lookalikes; the blue checkmark next to the name is the only reliable signal.

If this is your first time chatting with BotFather, tap Start at the bottom of the screen to open the conversation. Send the command /newbot. BotFather will reply asking what to call your bot.

2

Pick a name and a username

BotFather asks two things in turn:

  • Display name — what shows up at the top of the chat. Anything you like (e.g. "Lucy", "My Sutando", "Yumi").
  • Username — must be unique across all of Telegram and must end in "bot". Examples: lucy_sutando_bot, chi_assistant_bot. If your first choice is taken, BotFather will say so and you can try again.

Once the username is accepted, BotFather replies with a token — a long string of the form 123456789:ABCdefGHIjklMNOpqrSTUvwxYZ.

3

Paste the token into AG2 Space

BotFather's bot-detail page shows the token between Copy and Revoke buttons. Tap Copy.

Keep this private. The Telegram bot token grants full control over your bot. Don't paste it into chats, screenshots, or commits. If it leaks, tap Revoke (or send /revoke to BotFather) to invalidate the old token and get a fresh one.

Open AG2 Space → Settings → Channels → paste the token into the Telegram bot token field (the second one; Discord is above it). It's stored locally on your Mac (never logged, never sent to the cloud).

Scroll to the bottom of the Settings window and click Save. The setting only persists after you save — without this, the bot stays offline. Once saved, the field updates to a running badge once your agent connects to Telegram successfully.

4

Say hi

Back in Telegram, search for your bot by the username you picked (e.g. @lucy_sutando_bot) and tap to open the chat. You'll see a single START button at the bottom of an empty chat.

Tap START (or type /start), then send "hello" or "introduce yourself".

First time: it may take a minute or two for the local services to recognize the new Telegram bridge — if the bot doesn't reply immediately, give it ~2 minutes and try again before assuming something's wrong. When it works, you'll see your agent talking to you over Telegram, with the same context as your other channels. You're done.

How Sutando knows it's you

When you send your first DM to the bot after setup, your agent auto-trusts you as the owner — your Telegram user ID gets written to ~/.claude/channels/telegram/access.json so subsequent DMs from anyone else are dropped by default. You don't have to configure anything; the trust happens on the first message.

To allow another person (e.g., a teammate or family member) to also talk to your bot, run this in the Agent Console:

Agent Console
/telegram:access allow <telegram-user-id>

(They can find their Telegram user ID by messaging @userinfobot on Telegram.)

Coming soon: the AG2 team is working on a Settings UI to manage allowed Telegram senders without the CLI step.

Troubleshooting

"Username is invalid" or "already taken"

Telegram bot usernames have two hard rules: they must end in bot (case-insensitive — _bot, Bot, BOT all work), and they must be globally unique across Telegram. Pick something more specific — add your name, your stand's name, the year, anything to disambiguate. BotFather lets you try again as many times as you want.

Bot doesn't reply when I send "hello"

AG2 Space needs to be running on your Mac for the bot to respond — your agent lives inside it, and Telegram forwards messages to it via long-polling. If the app isn't running, launch it from Applications.

If the app IS running, the token may have been mistyped or truncated when you pasted. Reopen the BotFather chat, copy the token again (long-press the whole string, including the colon), and re-paste in AG2 Space Settings. The running badge will reappear once the connection is healthy.

I want to add the bot to a group chat — how?

Bots can join Telegram groups, but by default they only see messages where they're @-mentioned or replied to (this is Telegram's "privacy mode"). To add your Sutando bot to a group:

  • Open the group, tap the title to view group info
  • Tap Add Members → search for your bot by username
  • To @-mention the bot, type @your_bot_name followed by your message

If you want the bot to see all messages in the group (not just mentions), DM BotFather: /setprivacy → choose your bot → Disable. Most users don't need this; mentions are the safer default.

I lost the token — can I get it back?

Reopen BotFather, send /mybots, pick your bot, tap API Token. To rotate (invalidate the old token, get a new one), use /revoke instead. Paste the new token in AG2 Space Settings to reconnect.

Stuck? Ask in the Sutando Discord

Join the Sutando community Discord to ask questions, share what you've built, or get unstuck.

What's next

Connect Discord →Connect Slack →Back to docs →