# telegram

> Direct integration with Telegram Bot API for checking inbox messages and sending messages (text, photos, documents) to chats. Triggers when users request 'check Telegram inbox', 'check messages', 'send message to [chat]', or mention Telegram bot interactions. Requires TELEGRAM_BOT_TOKEN environment variable.

- Author: Markus Hauck
- Repository: markus1189/nixos-config
- Version: 20260206161921
- Stars: 5
- Forks: 0
- Last Updated: 2026-02-07
- Source: https://github.com/markus1189/nixos-config
- Web: https://mule.run/skillshub/@@markus1189/nixos-config~telegram:20260206161921

---

---
name: telegram
description: "Direct integration with Telegram Bot API for checking inbox messages and sending messages (text, photos, documents) to chats. Triggers when users request 'check Telegram inbox', 'check messages', 'send message to [chat]', or mention Telegram bot interactions. Requires TELEGRAM_BOT_TOKEN environment variable."
---

# 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:**
```bash
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

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

### Send Photo

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

### Send Document

```bash
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](https://github.com/eternnoir/pyTelegramBotAPI) (imported as `telebot`)
- [pyTelegramBotAPI docs](https://pytba.readthedocs.io/)

**Underlying API:** [Telegram Bot API](https://core.telegram.org/bots/api)
- Useful for understanding available methods, parameters, and error codes