Telegram Bot Skill

A skill that enables AI coding agents to send messages, files, and images on Telegram, and to read incoming updates from the bot, using only curl and the official Telegram Bot API.

---

What Is a Skill?

A skill is a structured prompt + a set of bash scripts that teach an AI coding agent how to perform a specific task. The agent reads SKILL.md to understand what to do and calls the scripts in scripts/ to interact with external services.

This skill is compatible with any agent that supports the skill/plugin convention (Claude Code, OpenCode, and similar tools).

---

Repository Structure

skills/
  telegram-bot/
    SKILL.md                        ← agent instructions and playbook
    scripts/
      telegram-get-me.sh            ← verify bot token (getMe)
      telegram-send-message.sh      ← send text message (sendMessage)
      telegram-send-document.sh     ← send document/file (sendDocument)
      telegram-send-photo.sh        ← send image (sendPhoto)
      telegram-get-updates.sh       ← read updates (getUpdates)

---

Installation

Copy the skills/ directory into your project root (or your global agent skills directory, depending on your agent's configuration):

cp -r skills/ /path/to/your/project/
chmod +x /path/to/your/project/skills/telegram-bot/scripts/*.sh

Important

Install required dependencies before running the scripts:

# Ubuntu/Debian
sudo apt install curl jq
# macOS
brew install curl jq

---

Configuration

Set the following environment variables before launching your agent:

# Required: bot token from @BotFather
export TELEGRAM_BOT_TOKEN="123456789:ABC-DEFghijklmn..."

# Optional: default chat ID (e.g. your personal Telegram ID)
export TELEGRAM_DEFAULT_CHAT_ID="123456789"

A .env.example file is included in the repository for reference. To make them persistent, add them to your ~/.bashrc, ~/.zshrc, or the project's .env file (loaded via direnv or similar).

Note

Consult your agent's documentation for the exact location where skills should be placed.

How to get a bot token

1. Open Telegram and search for @BotFather
2. Send /newbot and follow the instructions
3. Copy the token provided (format: 123456789:ABC-DEF...)

How to get your chat ID

1. Send a message to @userinfobot on Telegram
2. Or send a message to your bot and then run:

   curl -s "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/getUpdates" | jq '.result[].message.chat.id'

---

Usage

Once the skill is installed, ask your agent in natural language:

send "Deploy completed ✅" to the default Telegram chat
send the file ./reports/summary.pdf on Telegram to chat 123456789
show me the last 10 messages received by the bot

The agent will follow the instructions in SKILL.md and invoke the appropriate scripts.

---

System Dependencies

The scripts require:

• curl (almost always pre-installed)
• jq (for safe JSON generation in messages)

Install jq:

# Ubuntu/Debian
sudo apt install jq

# macOS
brew install jq

---

Manual Script Testing

You can run the scripts directly from the terminal to verify your setup:

# Verify token
bash skills/telegram-bot/scripts/telegram-get-me.sh

# Send a plain text message
bash skills/telegram-bot/scripts/telegram-send-message.sh \
  "123456789" "" "Hello from the terminal!"

# Send a message with HTML formatting
bash skills/telegram-bot/scripts/telegram-send-message.sh \
  "123456789" "HTML" "<b>Test</b> with <code>HTML</code>"

# Send a file
bash skills/telegram-bot/scripts/telegram-send-document.sh \
  "123456789" "./my-file.txt" "Here is the file"

# Read the last 5 updates
bash skills/telegram-bot/scripts/telegram-get-updates.sh "" 5

---

Supported Operations

Operation	Script	Telegram API method
Verify token	telegram-get-me.sh	getMe
Send text	telegram-send-message.sh	sendMessage
Send file	telegram-send-document.sh	sendDocument
Send image	telegram-send-photo.sh	sendPhoto
Read updates	telegram-get-updates.sh	getUpdates

---

Troubleshooting

Warning

If you see 409 Conflict on getUpdates, your bot has an active webhook. Remove it before polling:

curl -s "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/deleteWebhook"

Problem	Cause	Solution
401 Unauthorized	Wrong or expired token	Regenerate the token with @BotFather
chat not found	Wrong chat ID or bot not in chat	Verify chat ID; add the bot to the chat
403 Forbidden	Bot banned from the chat	Remove and re-add the bot
jq: command not found	jq not installed	Install jq (see Installation)
409 Conflict on getUpdates	Webhook is active	Remove the webhook before polling

---

License

See LICENSE.