Telegram capture

Send text and media to a personal Telegram bot; Trove stores a trove://type/classify/pending/1 event and guides you to classify it in the same chat. See planning/telegram-source for the full design.

Prerequisites

1. Build Trove and configure [modules].paths — see Quick Start.
2. [blobs] configured in trove.toml (media is stored via core.Put).
3. A Telegram bot token from @BotFather.

1. Create a bot

1. Open Telegram and message @BotFather.
2. Send /newbot and follow the prompts.
3. Copy the HTTP API token.

2. Find your chat ID

Message @userinfobot or send any message to your bot and inspect a one-off getUpdates response. Your user ID is the chat.id for direct messages.

3. Configure the module

You can configure in the module manifest or override from trove.toml (see Configuration).

Module manifest — edit modules/telegram-source/manifest.toml:

bot_token_env    = "TELEGRAM_BOT_TOKEN"
allowed_chat_ids = [123456789]   # your Telegram user/chat ID

[[bot.types]]
label       = "Quick note"
target_type = "trove://type/note/quick/1"

[[bot.types]]
label       = "Bookmark"
target_type = "trove://type/note/bookmark/1"

Set the token in your environment (recommended):

export TELEGRAM_BOT_TOKEN="123456:ABC…"

Or set bot_token directly in the manifest (do not commit secrets).

trove.toml overlay (optional) — keep secrets and chat IDs out of the repo:

[modules.settings.telegram-source]
allowed_chat_ids = [123456789]
bot_token_env    = "TELEGRAM_BOT_TOKEN"

[modules.config]
telegram-source = "/etc/trove/telegram.toml"

4. Build and start

make build

Ensure modules/ is in [modules].paths in trove.toml, then start Trove:

./bin/trove

5. Test the flow

1. Open a DM with your bot.
2. Send a photo or text message.
3. The bot replies with Captured 01J… and type buttons.
4. Tap Quick note (or another configured type).
5. Answer any field prompts, or /skip optional fields.
6. Confirm with Logged as trove://type/note/quick/1 (01J…).

Query records via MCP search_records or the capture-classifier GET /pending endpoint.

Power-user commands

Security

• Only chats in allowed_chat_ids are processed; others are ignored silently.
• Keep your bot username private and prefer bot_token_env over inline tokens.
• Telegram Bot API has no inbound auth — the allowlist is the security boundary.

Troubleshooting