# Telegram Bot
> Send text messages and files on Telegram, or read the latest updates received by the bot. Use this skill when the user asks to send content (text, reports, logs, screenshots) to a Telegram chat or channel, or to inspect incoming messages.
- Skill: `leo-capvano/telegram-bot` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx skillmds@latest add leo-capvano/telegram-bot`
- Raw SKILL.md: https://api.skillmd.com/api/skills/leo-capvano/telegram-bot/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: leo-capvano (https://skillmd.com/u/leo-capvano)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/leo-capvano/telegram-bot
---
# Skill: Telegram Bot
This skill allows the agent to interact with the **Telegram Bot API** via `curl`,
using bash scripts included in the `./scripts/` directory.
---
## Required Prerequisites
Before performing any operation, verify that the following environment variables
are set in the environment:
| Variable | Required | Description |
|---------------------------|:--------:|------------------------------------------------------------------|
| `TELEGRAM_BOT_TOKEN` | ✅ Yes | Bot token obtained from @BotFather |
| `TELEGRAM_DEFAULT_CHAT_ID`| ❌ No | Default numeric chat ID (e.g. your personal chat ID) |
If `TELEGRAM_BOT_TOKEN` is not set, **stop** and ask the user to set it before proceeding.
**Dependencies**: The scripts require `curl` and `jq` to be installed.
---
## Supported Actions
### 1. Verify bot token (`getMe`)
On first setup or if you suspect a token issue, run the verification command:
```!
bash "./scripts/telegram-get-me.sh"
```
If the response contains `"ok":true`, the bot is configured correctly. If it contains
`"ok":false`, inform the user that the token is invalid.
---
### 2. Send a text message
**When to use**: the user asks to send text to Telegram.
**Steps**:
1. Determine the `CHAT_ID`:
- If the user provides it explicitly (e.g. `123456789` or `-100123456`), use it.
- Otherwise use `$TELEGRAM_DEFAULT_CHAT_ID` if set, notifying the user.
- If neither is available, **ask** the user for the chat ID before proceeding.
2. **Always ask for explicit confirmation** before sending. Show:
- Recipient (chat ID)
- Preview of the text
3. Build the text. You can use **HTML** formatting (e.g. `bold`, ``)
or **Markdown** (e.g. `**bold**`, `` `code` ``).
4. Run:
```!
bash "./scripts/telegram-send-message.sh" "" "" ""
```
Where `` is `HTML`, `MarkdownV2`, or leave it empty `""` for plain text.
5. Parse the JSON response:
- `"ok":true` → message sent successfully. Inform the user.
- `"ok":false` → report the `description` field to the user with corrective suggestions.
---
### 3. Send a document or file
**When to use**: the user asks to send a file (report, log, screenshot, etc.).
**Steps**:
1. Determine the `CHAT_ID`:
- If the user provides it explicitly, use it.
- Otherwise use `$TELEGRAM_DEFAULT_CHAT_ID` if set, notifying the user.
- If neither is available, **ask** the user for the chat ID before proceeding.
2. Verify that the file path exists and is accessible.
3. **Ask for confirmation** before sending (file + recipient).
4. Run:
```!
bash "./scripts/telegram-send-document.sh" "" "" ""
```
`` is optional: you can pass `""` if you don't want a caption.
5. Interpret the response as for text messages.
**Note**: for files larger than 50 MB, the standard Bot API is not supported. Inform the user.
---
### 4. Send an image
**When to use**: the user asks to send an image (PNG, JPG, etc.).
**Steps**: Same as sending a document. Determine chat ID, verify the file exists, ask for confirmation, then run:
```!
bash "./scripts/telegram-send-photo.sh" "" "" ""
```
**Note**: Images larger than 10 MB are not supported. Use `telegram-send-document.sh` instead for large images.
---
### 5. Read the latest updates (`getUpdates`)
**When to use**: the user wants to inspect incoming messages from the bot.
**Important warning**: `getUpdates` is incompatible with webhooks. If a webhook is active,
this call will return an error. Inform the user before proceeding.
```!
bash "./scripts/telegram-get-updates.sh" "" ""
```
- ``: use `""` to read all updates, or `update_id + 1` of the last read
update to scroll the queue.
- ``: number of updates to read (1–100). Recommended default: `20`.
Parse the returned JSON and list in readable form:
- `update_id`
- Update type (message, callback_query, etc.)
- Sender (name + username if present)
- Message text or content type
---
## Security Guidelines
- ❌ **Do not derive** tokens or secrets from the conversation context.
- ❌ **Do not perform** bulk sends or automatic loops without explicit human oversight.
- ✅ For batch operations, show a summary and ask for approval before starting.
---
## Common Error Handling
| Telegram Error | Likely Cause | Solution |
|----------------------------------------|----------------------------------------|----------------------------------------------|
| `401 Unauthorized` | Wrong or revoked token | Check `TELEGRAM_BOT_TOKEN` |
| `400 Bad Request: chat not found` | Wrong chat ID or bot not in chat | Verify chat ID; add bot to the chat |
| `403 Forbidden` | Bot banned from chat | Use another chat or add the bot |
| `429 Too Many Requests` | Rate limit reached | Wait the indicated number of seconds |
| `TELEGRAM_BOT_TOKEN not set` | Missing environment variable | Set `TELEGRAM_BOT_TOKEN` in the environment |
---
## Quick Examples
**Send a message to the default chat:**
```
send "Deploy completed successfully" to the default Telegram chat
```
**Send a log file:**
```
send the file ./logs/app.log on Telegram to chat ID 123456789
```
**Read the last 10 messages:**
```
show me the last 10 updates received by the bot
```