Telegram Bot Integration

Heartbit integrates with Telegram as an interactive channel for daemon mode, enabling users to chat with agents directly from Telegram.

Features

• Direct messages — users interact with the agent via Telegram DMs
• Streaming responses — agent responses stream in real-time
• Human-in-the-loop (HITL) — approval buttons for tool execution
• Keyboard menus — structured question/answer via Telegram keyboard buttons
• Access control — whitelist users/groups, rate limiting
• Session management — per-chat session context

Setup

1. Create a bot via @BotFather on Telegram
2. Set the HEARTBIT_TELEGRAM_TOKEN environment variable
3. Start the daemon: heartbit daemon --config heartbit.toml
4. Message your bot on Telegram

Configuration

Set the Telegram bot token via environment variable:

export HEARTBIT_TELEGRAM_TOKEN=<your-bot-token>

Or configure alongside your daemon:

[daemon]
bind = "127.0.0.1:3000"

# Telegram is activated when HEARTBIT_TELEGRAM_TOKEN is present
# in the environment. The daemon config controls other settings.

Architecture

The Telegram adapter (TelegramBridge) implements the InteractionBridge trait, connecting Telegram’s messaging API to the agent’s callback system:

Callback	Behavior
OnText	Streams text responses back to Telegram
OnInput	Receives user input from Telegram messages
OnApproval	Sends approval buttons, waits for user response
OnQuestion	Sends structured questions with keyboard buttons

Feature Flag

Telegram support requires the telegram feature flag:

cargo build --features telegram

The CLI binary (heartbit-cli) includes it via the full feature.