# Telecli > This skill should be used when the user asks to "send a Telegram message", "poll for Telegram updates", "check Telegram bot status", "respond to Telegram messages", "react to messages", "manage Telegram bot", or mentions Telegram Bot API operations. Provides comprehensive guidance for using the tg CLI to interact with Telegram bots. Use when this capability is needed. - Skill: `tomevault-io/telecli` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/telecli` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/telecli/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Web & Frontend - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/telecli --- # Telecli - Telegram Bot CLI Control Telegram bots via the `tg` command-line interface. All commands output JSON for easy parsing and automation. ## Setup Configure the bot token (one-time setup): ```bash # Global config (recommended) tg config token # Local config (per-directory) tg config token --local # Or use environment variable export TELEGRAM_BOT_TOKEN="your_bot_token" ``` Get a bot token from [@BotFather](https://t.me/BotFather) on Telegram. ## Core Commands ### Bot Info ```bash tg me # Get bot information tg config token # Show configured tokens tg config path # Show config file paths ``` ### Polling for Updates ```bash # Wait indefinitely for updates (loops with 50s timeout until updates arrive) tg updates poll # With offset (skip already-processed updates) tg updates poll --offset 729538157 # Single poll with explicit timeout (for scripts/hooks) tg updates poll --timeout 5 ``` **Polling loop pattern:** 1. Call `tg updates poll` (blocks until updates arrive) 2. Process returned messages 3. Calculate next offset: `max(update_id) + 1` 4. Repeat with `--offset ` ### Sending Messages ```bash # Simple text message tg message send "Hello!" # Reply to a specific message tg message send "Thanks!" --reply-to # With HTML formatting tg message send "Bold text" --parse-mode HTML # Forward a message tg message forward # Edit a message tg message edit "Updated text" # Delete a message tg message delete ``` ### Reactions ```bash # Add reaction to a message tg reaction set "👍" tg reaction set "😂" ``` ### Media ```bash # Send photo tg photo send /path/to/image.jpg tg photo send /path/to/image.jpg --caption "Nice photo!" # Send document tg document send /path/to/file.pdf # Send voice message tg voice send /path/to/audio.ogg # Download file from Telegram tg file download /path/to/save ``` ### Chat Management ```bash # Get chat info tg chat get # Get chat member count tg chat members # Get chat administrators tg chat admins # Leave a chat tg chat leave ``` ## Update Processing Updates from `tg updates poll` return JSON with this structure: ```json { "ok": true, "result": [ { "update_id": 729538157, "message": { "message_id": 123, "from": { "id": 12345678, "first_name": "User", "username": "username" }, "chat": { "id": -123456789, "title": "Group Name", "type": "group" }, "date": 1704067200, "text": "Hello bot!" } } ] } ``` **Key fields:** - `update_id`: Use max + 1 as next offset - `message.chat.id`: Target for replies - `message.message_id`: Use for replies/reactions - `message.from`: Sender information - `message.text`: Message content **Update types:** - `message`: New message - `edited_message`: Edited message - `callback_query`: Inline button press - `inline_query`: Inline mode query ## Common Patterns ### Reply to Messages ```bash # Extract info from update chat_id=$(echo "$update" | jq -r '.message.chat.id') message_id=$(echo "$update" | jq -r '.message.message_id') text=$(echo "$update" | jq -r '.message.text') # Send reply tg message send "$chat_id" "You said: $text" --reply-to "$message_id" ``` ### Continuous Polling Loop ```bash offset="" while true; do # Blocks until updates arrive (no --timeout = infinite polling) result=$(tg updates poll $offset) # Process updates echo "$result" | jq -c '.result[]' | while read update; do # Handle each update chat_id=$(echo "$update" | jq -r '.message.chat.id') text=$(echo "$update" | jq -r '.message.text') # Respond to messages if [ -n "$text" ]; then tg message send "$chat_id" "Received: $text" fi done # Update offset new_offset=$(echo "$result" | jq '[.result[].update_id] | max + 1 // empty') if [ -n "$new_offset" ]; then offset="--offset $new_offset" fi done ``` ### Check for Mentions ```bash # Check if bot was mentioned if echo "$text" | grep -qi "@BotUsername"; then tg message send "$chat_id" "You called?" fi ``` ## Error Handling All commands return JSON with `ok` field: ```json {"ok": true, "result": {...}} # Success {"ok": false, "error": "..."} # Error ``` Check `ok` field before processing results: ```bash result=$(tg message send 123 "Hello") if echo "$result" | jq -e '.ok' > /dev/null; then echo "Message sent!" else echo "Error: $(echo "$result" | jq -r '.error')" fi ``` ## Additional Resources ### Reference Files For complete command reference with all options: - **`references/commands.md`** - Full command reference with all flags and options ### Chat ID Types - **Positive numbers**: Private chats (user IDs) - **Negative numbers**: Groups and supergroups - **@username**: Public channels/groups with usernames --- > Converted and distributed by [TomeVault](https://tomevault.io/claim/danizord) — claim your Tome and manage your conversions.