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. <b>bold</b>, <code>) or Markdown (e.g. **bold**, `code`).

4. Run:

bash "./scripts/telegram-send-message.sh" "<CHAT_ID>" "<PARSE_MODE>" "<TEXT>"

Where <PARSE_MODE> 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" "<CHAT_ID>" "<FILE_PATH>" "<CAPTION>"

<CAPTION> 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" "<CHAT_ID>" "<FILE_PATH>" "<CAPTION>"

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" "<OFFSET>" "<LIMIT>"

• <OFFSET>: use "" to read all updates, or update_id + 1 of the last read update to scroll the queue.
• <LIMIT>: 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