Skip to main content
Connect Spacebot to Telegram. Takes about 2 minutes. You need a Bot Token from Telegram’s BotFather.

​
Step 1: Create a Bot

1

Message BotFather

Open Telegram and message @BotFather. Send /newbot and follow the prompts:
  • Name: The display name (e.g., “My Spacebot”)
  • Username: Must end in bot (e.g., my_spacebot_bot)
2

Copy the Token

BotFather replies with your bot token. It looks like:
123456789:ABCdefGHIjklMNOpqrsTUVwxyz
Keep this token safe — you’ll need it in a moment.

​
Step 2: Configure Privacy (Optional)

By default, bots in groups only see messages that mention them directly, reply to them, or start with a /command. If you want the bot to see all messages in a group:
1

Disable Privacy Mode

Send /setprivacy to BotFather and select Disable.
2

Re-add the Bot

Privacy mode must be disabled before adding the bot to a group. If the bot is already in a group, remove it and re-add it after changing the setting.

​
Step 3: Add Token to Spacebot

config.toml
[messaging.telegram]
enabled = true
token = "123456789:ABCdefGHIjklMNOpqrsTUVwxyz"

[[bindings]]
agent_id = "main"
channel = "telegram"
You can also reference environment variables:
config.toml
[messaging.telegram]
enabled = true
token = "env:TELEGRAM_BOT_TOKEN"
Token changes in config require a restart.

​
Step 4: Add the Bot

Add the bot to a group, or start a DM with it by searching for its username in Telegram.

​
Verify It’s Working

Send a message to the bot. You should see:
  1. A typing indicator while it processes
  2. A reply from the bot
If the bot doesn’t respond, check the troubleshooting section below.

​
Filtering

​
Restrict to Specific Chats

By default the bot responds in any chat it’s added to. To limit it, add chat IDs to your binding.
config.toml
[[bindings]]
agent_id = "main"
channel = "telegram"
chat_id = "-100123456789"
Without chat_id, the bot responds in all chats.

​
Finding Chat IDs

  • DMs: The chat ID is the user’s Telegram user ID. You can find it by messaging @userinfobot.
  • Groups: Add the bot to the group, send a message, and check the Spacebot logs — the conversation_id will show as telegram:<chat_id>. Group IDs are negative numbers (e.g., -100123456789).

​
DM Filtering

By default, DMs from anyone are accepted. To restrict to specific users:
config.toml
[messaging.telegram]
dm_allowed_users = ["123456789", "987654321"]
When the list is empty (default), all DMs are accepted. Permission changes hot-reload within a couple seconds — no restart needed.

​
Multiple Chats, Multiple Agents

Route different Telegram chats to different agents.
config.toml
[[bindings]]
agent_id = "community"
channel = "telegram"
chat_id = "-100111111111"

[[bindings]]
agent_id = "team"
channel = "telegram"
chat_id = "-100222222222"
Each agent has its own memory, identity, and conversation history.

​
Media Attachments

Telegram supports sending and receiving:
  • Images (JPEG, PNG, WebP)
  • Documents (PDF, ZIP, any file type)
  • Audio files
  • Video files
Files are automatically downloaded and included in the MessageContent::Media variant with authenticated URLs.
Telegram has a 20MB file size limit for bots. Larger files must be sent as URLs instead.

​
Rich Messages

Telegram supports:

​
Markdown Formatting

Use standard Markdown syntax:
  • **bold**
  • *italic*
  • `code`
  • code blocks

​
Inline Keyboards

Interactive buttons attached to messages. Spacebot converts OutboundResponse::RichMessage with interactive elements to Telegram inline keyboards.

​
Polls

Create polls with:
  • Up to 10 options
  • Anonymous or non-anonymous
  • Quiz mode with correct answer

​
Limitations

  • Message length: 4096 characters. Longer messages are automatically split.
  • File size: 20MB for bot uploads
  • Reaction support: Limited to emoji reactions supported by the specific chat
  • Streaming: Message edits have a 1-second minimum interval to avoid rate limits

​
Troubleshooting

SymptomCauseFix
401 Unauthorized on startupInvalid tokenGet a fresh token from BotFather
Bot doesn’t respond in groupPrivacy modeSend /setprivacy → Disable to BotFather, then remove and re-add the bot
Bot doesn’t respond to DMsDM filteringAdd user ID to dm_allowed_users, or clear the list to allow all
Reaction fails silentlyUnsupported emojiTelegram limits reactions to each chat’s configured emoji set
Edits fail with rate limitToo frequent updatesStreaming edits are throttled to 1 second intervals automatically

​
Next Steps

Configure Permissions

Set up chat filters and access control

Media Handling

Learn how file attachments work

Agent Configuration

Create multiple agents for different chats

Build docs developers (and LLMs) love

Get started for freeTalk to us