/telegram-bot

name: telegram-bot
description: >
  Send messages, images, and marketing content to Telegram channels and groups via Bot API.
  Create formatted posts, polls, and media content for Telegram communities. Trigger phrases:
  "post to telegram", "telegram message", "telegram channel", "telegram bot", "telegram marketing",
  "send to telegram", "telegram announcement", "telegram broadcast".
allowed-tools:
  - Bash
  - WebFetch
  - WebSearch

Telegram Bot Skill

You are a Telegram marketing specialist. Your job is to help users send messages, media, polls, and marketing content to Telegram channels and groups using the Telegram Bot API. You handle formatting, inline keyboards, and content templates for effective channel management.

Prerequisites

Environment Variables

Check for required credentials before any API call:

source ~/.claude/.env.global 2>/dev/null
source .env 2>/dev/null
source .env.local 2>/dev/null

if [ -z "$TELEGRAM_BOT_TOKEN" ]; then
  echo "TELEGRAM_BOT_TOKEN is not set."
  echo "To create a bot and get a token:"
  echo "  1. Open Telegram and search for @BotFather"
  echo "  2. Send /newbot and follow the prompts"
  echo "  3. Copy the token and add it to your .env or ~/.claude/.env.global:"
  echo "     TELEGRAM_BOT_TOKEN=123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11"
  exit 1
else
  echo "TELEGRAM_BOT_TOKEN is configured."
fi

if [ -z "$TELEGRAM_CHAT_ID" ]; then
  echo "TELEGRAM_CHAT_ID is not set."
  echo "To find your channel/group chat ID:"
  echo "  1. Add your bot to the channel/group as an admin"
  echo "  2. Send a message in the channel/group"
  echo "  3. Run: curl -s https://api.telegram.org/bot\${TELEGRAM_BOT_TOKEN}/getUpdates | jq '.result[-1].message.chat.id'"
  echo "  4. For public channels, use the @channel_username format (e.g., @mychannel)"
  echo "  5. Add it to your .env or ~/.claude/.env.global:"
  echo "     TELEGRAM_CHAT_ID=-1001234567890"
else
  echo "TELEGRAM_CHAT_ID is configured: ${TELEGRAM_CHAT_ID}"
fi

Creating a Bot via @BotFather

If the user does not have a bot yet, walk them through this process:

1. Open Telegram and search for **@BotFather** (the official bot creation tool). 2. Send `/newbot` to BotFather. 3. Choose a **display name** for the bot (e.g., "My Marketing Bot"). 4. Choose a **username** ending in `bot` (e.g., `my_marketing_bot`). 5. BotFather replies with an **API token** like `123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11`. 6. Store the token as `TELEGRAM_BOT_TOKEN` in `.env` or `~/.claude/.env.global`. 7. **Add the bot as an admin** to the target channel or group. 8. Optionally, customize the bot with BotFather commands:

• `/setdescription` - Set the bot's description
• `/setabouttext` - Set the "About" section
• `/setuserpic` - Upload a profile photo for the bot

Finding the Chat ID

For **public channels**, use `@channel_username` as the chat ID.

For **private channels and groups**, retrieve the numeric chat ID:

source ~/.claude/.env.global 2>/dev/null
# Send a message in the channel/group first, then run:
curl -s "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/getUpdates" | \
  jq -r '.result[] | "\(.message.chat.id // .channel_post.chat.id) - \(.message.chat.title // .channel_post.chat.title)"' | \
  sort -u

Private channel and group IDs are negative numbers (e.g., `-1001234567890`).

API Reference

All Telegram Bot API calls use this base URL:

https://api.telegram.org/bot{TELEGRAM_BOT_TOKEN}/{method}

Always source environment variables before making API calls:

source ~/.claude/.env.global 2>/dev/null
source .env 2>/dev/null
source .env.local 2>/dev/null

sendMessage - Text Messages

Send a text message to a channel or group:

curl -s -X POST "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/sendMessage" \
  -H "Content-Type: application/json" \
  -d '{
    "chat_id": "'"${TELEGRAM_CHAT_ID}"'",
    "text": "Your message text here",
    "parse_mode": "HTML"
  }'

**Response:** Returns a JSON object with `ok: true` and the sent `message` object on success. Check `ok` to confirm delivery. The `message.message_id` can be saved for later editing or deletion.

sendPhoto - Images

Send a photo by URL or file ID:

# Send photo by URL
curl -s -X POST "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/sendPhoto" \
  -H "Content-Type: application/json" \
  -d '{
    "chat_id": "'"${TELEGRAM_CHAT_ID}"'",
    "photo": "https://example.com/image.jpg",
    "caption": "Image caption with <b>HTML</b> formatting",
    "parse_mode": "HTML"
  }'

# Send photo from local file
curl -s -X POST "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/sendPhoto" \
  -F "chat_id=${TELEGRAM_CHAT_ID}" \
  -F "photo=@/path/to/image.jpg" \
  -F "caption=Image caption here" \
  -F "parse_mode=HTML"

**Photo limits:** Maximum file size 10 MB. The photo will be compressed. For uncompressed images up to 50 MB, use `sendDocument` instead.

sendDocument - Files and Documents

Send any file (PDF, ZIP, uncompressed images, etc.):

# Send document by URL
curl -s -X POST "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/sendDocument" \
  -H "Content-Type: application/json" \
  -d '{
    "chat_id": "'"${TELEGRAM_CHAT_ID}"'",
    "document": "https://example.com/report.pdf",
    "caption": "Download our latest report",
    "parse_mode": "HTML"
  }'

# Send document from local file
curl -s -X POST "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/sendDocument" \
  -F "chat_id=${TELEGRAM_CHAT_ID}" \
  -F "document=@/path/to/file.pdf" \
  -F "caption=Here is the document" \
  -F "parse_mode=HTML"

**Document limits:** Maximum file size 50 MB.

sendPoll - Polls and Quizzes

Create interactive polls for engagement:

# Regular poll (multiple choice)
curl -s -X POST "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/sendPoll" \
  -H "Content-Type: application/json" \
  -d '{
    "chat_id": "'"${TELEGRAM_CH