Telegram Bot Setup

This guide walks through setting up the agent with a real Telegram bot.

Prerequisites

• A running agent daemon (see Getting Started)
• A Telegram account

Step 1: Create a Bot with BotFather

1. Open Telegram and message @BotFather
2. Send /newbot and follow the prompts
3. Choose a name (e.g. "My Agent") and username (e.g. my_agent_bot)
4. BotFather responds with a token: 123456:ABC-DEF...

Step 2: Configure the Agent

Add the token to .env:

echo 'TELEGRAM_BOT_TOKEN=123456:ABC-DEF...' >> .env

Optional: set a default notification chat ID in agent.toml:

[gateway.telegram]
notify_chat_id = "7093765073"

This is the chat ID the agent will use when it sends proactive notifications (e.g., from cron jobs or pulse tasks). You can find your chat ID by messaging @userinfobot.

Step 3: Start the Daemon

gleam run -m agent_app

You should see startup log messages for the Telegram gateway. The bot is now polling for messages.

Step 4: Test

Message your bot on Telegram. It should respond within a few seconds. The agent uses the same configuration (model, persona, tools) as the CLI REPL.

Troubleshooting

Bot doesn't respond:

• Check that TELEGRAM_BOT_TOKEN is set correctly in .env
• Verify the daemon is running and the Telegram gateway shows as active: gleam run -m agent_admin gateways status
• Check daemon logs for error messages

Messages are slow:

• The Telegram gateway uses long-polling with a configurable timeout. Reduce polling_timeout in agent.toml for faster response, at the cost of more API calls.

Multiple bots fighting over messages:

• Ensure only one daemon instance is running. The deduplication window (dedup_window_ms) helps, but concurrent instances will still race.

DND (Do Not Disturb)

Once the bot is running, you can manage quiet hours via the admin CLI:

# Check current DND rules
gleam run -m agent_admin dnd status

# Add a quiet window (UTC times)
gleam run -m agent_admin dnd set 22:00 08:00

# Toggle indefinite DND
gleam run -m agent_admin dnd indefinite

The agent won't send proactive notifications during DND windows. Direct replies to messages are always delivered.