Add Telegram Channel
Walk the user through adding a Telegram bot channel to Talon. One question at a time.
Phase 1: Pre-flight
Check if a telegram channel already exists:
npx talonctl list-channels
If one exists, ask the user if they want to add another or reconfigure.
Phase 2: Create the Bot
Ask: "Do you already have a Telegram bot token?"
If no, walk them through it:
- Open Telegram and search for @BotFather
- Send
/newbot- Choose a display name (e.g. "Talon Assistant")
- Choose a username — must end with
bot(e.g.talon_assistant_bot)- BotFather will reply with a token like
123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11- Copy that token
Wait for the user to provide the token. Never store the actual token in config — use an env var placeholder.
Phase 3: Add the Channel
Ask for a channel name (suggest my-telegram), then:
npx talonctl add-channel --name <name> --type telegram
Then edit talond.yaml to set the config section for this channel:
config:
botToken: ${TELEGRAM_BOT_TOKEN}
pollingTimeoutSec: 30
Tell the user to add to .env:
TELEGRAM_BOT_TOKEN=<their-actual-token>
Phase 4: Restrict Access (Recommended)
Ask: "Do you want to restrict the bot to specific chats?"
If yes, explain how to get chat IDs:
- Start a conversation with your bot in Telegram
- Send any message
- Open
https://api.telegram.org/bot<TOKEN>/getUpdatesin a browser- Find
"chat":{"id":12345678}— that's your chat ID- For groups: add the bot to the group, send a message, check getUpdates again (group IDs are negative numbers like
-1001234567890)
Then edit the channel config to add:
config:
botToken: ${TELEGRAM_BOT_TOKEN}
pollingTimeoutSec: 30
allowedChatIds:
- "12345678"
Phase 5: Bind a Persona
npx talonctl list-personas
Ask which persona to bind, then:
npx talonctl bind --persona <name> --channel <channel-name>
If no personas exist yet, suggest creating one first.
Phase 6: Validate
npx talonctl env-check
npx talonctl doctor
Report any issues and help fix them.
Phase 7: Group Chat Setup
If the user mentions group chats, explain:
Group Privacy: By default, Telegram bots only see messages that @mention them in groups. To let the bot see all messages:
- Open @BotFather
- Send
/mybotsand select your bot- Go to Bot Settings > Group Privacy > Turn off
After changing this, remove and re-add the bot to the group for it to take effect.
Phase 8: Verify
Tell the user:
- Make sure talond is running (or restart it)
- Send a message to the bot in Telegram
- You should get a response within a few seconds
If it doesn't work:
# Check if token is valid
curl -s "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/getMe"
# Check logs
journalctl --user -u talond -f
Images (optional)
Telegram photos and image-MIME documents are ingested automatically. To let the bound persona answer what a photo shows it needs exactly two things — existing personas gain neither on upgrade:
npx talonctl set-capabilities --persona <persona> --add subagent.invoke:*
plus vision in that persona's subagents list in talond.yaml (there is no
talonctl command for persona sub-agent assignment). The shipped vision manifest
declares requiredCapabilities: [], so no image capability is part of an
Inspection. Pixels go only to the vision sub-agent; the persona itself stays
text-only.
Separately, image.read:thread is an independent model-free lookup grant for
the thread's Images and saved Findings (image_lookup). It needs no vision
assignment and never calls a model — recommended so the persona can re-read an
existing Finding, but not required for Inspections.
Telegram-specific behaviour worth warning the user about:
- Photos usually lose EXIF. Telegram recompresses photos, so GPS and capture time are typically gone. When metadata matters, tell the user to send the original as a document — for a format Talon already accepts (see below); this helps but cannot guarantee preservation.
- HEIC is rejected (
unsupported_mime), which matters because iOS photos default to it. It must be converted to JPEG, static PNG, or static WebP before sending. Sending a HEIC as a document does not work: an unsupported image MIME in a document is rejected asunsupported_mimewithout even being downloaded, and it still burns one of the message's upload slots. - Albums stay separate messages, each producing its own Image; a burst is not coalesced.
- Up to 5 images per message by default (
images.maxPerMessage); the rest are rejectedcount_limitwithout being downloaded. - Polling is sequential. While an image-bearing message is fetched and normalized that connector delivers nothing else — up to roughly 120 seconds, affecting every chat on this bot token.
- Normalized files are deleted after
images.retentionHours(default 24h). Image records, GPS/EXIF and saved Findings persist beyond that.
Troubleshooting
| Problem | Fix |
|---|---|
| Bot not responding | Check TELEGRAM_BOT_TOKEN in .env, restart talond |
| Bot only responds to @mentions in groups | Disable Group Privacy in BotFather (see Phase 7) |
| "Unauthorized" errors in logs | Token is wrong or revoked — get new one from BotFather |
| Bot responds to strangers | Add allowedChatIds to config (see Phase 4) |
| Duplicate responses | Check if multiple instances of talond are running |
Config Reference
channels:
- name: my-telegram
type: telegram
config:
botToken: ${TELEGRAM_BOT_TOKEN} # Required
pollingTimeoutSec: 30 # Optional (default: 30)
allowedChatIds: # Optional — restrict to specific chats
- "12345678"
How It Works
- Talon uses long-polling (
getUpdates) — no webhook URL or public server needed - Each Telegram chat maps to one Talon thread
- Of a photo's renditions, the largest one that fits the size limits becomes a single Image; the others are not separate Images
- Markdown formatting is auto-converted to Telegram's MarkdownV2
- Typing indicator is shown while the agent processes