/telegram

telegram

Instructions

Use this skill to interact with Telegram via the Bot API. All operations use curl against https://api.telegram.org/bot<TOKEN>/....

Prerequisites

The environment variable TELEGRAM_BOT_TOKEN must be set to a valid Telegram Bot API token (obtained from @BotFather). The variable TELEGRAM_CHAT_ID should be set to the target chat/group/channel ID for sending messages.

Sending a message

curl -s "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/sendMessage" \
  -d chat_id="${TELEGRAM_CHAT_ID}" \
  -d text="Hello from shellm" \
  -d parse_mode=Markdown

Sending a file/document

curl -s "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/sendDocument" \
  -F chat_id="${TELEGRAM_CHAT_ID}" \
  -F document=@/path/to/file.txt

Getting updates (receiving messages)

Poll for new messages using getUpdates. Use offset to acknowledge previously seen updates and only receive new ones.

# Get latest updates
curl -s "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/getUpdates" \
  -d limit=10 \
  -d timeout=0

# Acknowledge up to update_id 12345 and get only newer updates
curl -s "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/getUpdates" \
  -d offset=12346 \
  -d limit=10

Parse the JSON response with jq:

curl -s "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/getUpdates" \
  | jq -r '.result[] | "\(.update_id) \(.message.from.username): \(.message.text)"'

Replying to a specific message

curl -s "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/sendMessage" \
  -d chat_id="${TELEGRAM_CHAT_ID}" \
  -d text="Reply text" \
  -d reply_to_message_id=MESSAGE_ID

Getting chat info

curl -s "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/getChat" \
  -d chat_id="${TELEGRAM_CHAT_ID}" | jq .

Error handling

All Telegram API responses return JSON with an ok field. Check it:

response=$(curl -s "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/sendMessage" \
  -d chat_id="${TELEGRAM_CHAT_ID}" \
  -d text="test")
if [ "$(echo "$response" | jq -r '.ok')" != "true" ]; then
  echo "Telegram API error: $(echo "$response" | jq -r '.description')" >&2
fi

Rate limits

Telegram limits bots to ~30 messages/second to different chats, and ~20 messages/minute to the same chat. Add short delays between batch sends.