Telegram Bot Integration

Interact directly with Telegram Bot API to check messages and send content to chats. Scripts use Nix shebangs to automatically provide dependencies.

Checking Inbox Messages

Use scripts/check_messages.py to retrieve new messages.

What it does:

• Polls Telegram API for new updates
• Downloads photos and documents to ~/Downloads/ (or TELEGRAM_DOWNLOAD_DIR)
• Displays message details (chat ID, user, timestamp, content)
• Marks messages as read after displaying

Usage:

env TELEGRAM_BOT_TOKEN="$(pass api/telegram)" ./scripts/check_messages.py

Optional: Set custom download directory with TELEGRAM_DOWNLOAD_DIR environment variable.

Output format:

Chat ID: 12345
User: John Doe
Username: @johndoe
Time: 2025-01-10 14:30:45
Message ID: 789
Text: Hello bot!
Photo: /home/user/Downloads/telegram_12345_789_photo.jpg

Sending Messages

Use scripts/send_message.py to send content via Telegram.

Send Text

env TELEGRAM_BOT_TOKEN="$(pass api/telegram)" ./scripts/send_message.py 12345 "Hello from Claude"

Send Photo

env TELEGRAM_BOT_TOKEN="$(pass api/telegram)" ./scripts/send_message.py 12345 --photo ~/image.png --caption "Optional caption"

Send Document

env TELEGRAM_BOT_TOKEN="$(pass api/telegram)" ./scripts/send_message.py 12345 --document ~/report.pdf --caption "Optional caption"

Important Constraints

Bot limitations:

• Cannot message users who haven't started conversation with the bot (must send /start first)
• Cannot message users who have blocked the bot
• Bot must be added to groups before messaging them

Rate limits:

• ~30 messages/second to different chats
• ~1 message/second to same chat

File size limits:

• Photos: 10MB max
• Documents/Videos: 50MB max

Error Handling

Common errors are handled automatically by the scripts:

• 401: Invalid bot token
• 403: User hasn't started conversation or blocked bot
• 429: Rate limit - scripts report retry delay
• File not found: Clear error message with filepath

Chat IDs

Default chat ID: 299952716 (user @markus1189)

When sending messages without a specified chat ID, use the default. To discover other chat IDs:

1. Check inbox output (displays chat ID for each message)
2. Send a message to the bot and check inbox

Stateless Operation

This skill is stateless. Telegram's API automatically tracks which messages have been read using update offsets. No local state storage needed.

API Documentation

Library used: pyTelegramBotAPI (imported as telebot)

• pyTelegramBotAPI docs

Underlying API: Telegram Bot API

• Useful for understanding available methods, parameters, and error codes