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.

1. 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.

1. Verify that the file path exists and is accessible.
2. Ask for confirmation before sending (file + recipient).
3. 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

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [leo-capvano](https://github.com/leo-capvano)
- **Source:** [leo-capvano/telegram-skill](https://github.com/leo-capvano/telegram-skill)
- **License:** MIT

Install and usage instructions live in the source repository linked above.