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:

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

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