Telegram Skill

Auto-activate for Telegram message sending, daemon control, or bot configuration.

Setup Instructions (For CLI Agents)

When helping the user set up the Telegram bot, follow these steps:

Step 1: Install Dependencies

pip install -r requirements.txt

Step 2: Create Environment File

Copy the template and help the user fill in credentials:

cp .env.example .env

Required credentials (user must obtain):

Step 3: Create Logs Directory

mkdir -p logs

Step 4: Start the Bot

python telegram_listener.py --daemon

Step 5: Verify Setup

python telegram_listener.py --status

Daemon Control

Send Messages

Command 'telegram' (see below for command content) send "Your message here"
Command 'telegram' (see below for command content) brief          # Send morning briefing now
Command 'telegram' (see below for command content) alert "msg"    # System alert notification

Architecture

Two-tier — daemon is standalone Python, cannot call Claude MCP directly:

Key Files

• Script: telegram_listener.py + telegram_helpers.py
• PID: /tmp/telegram_listener.pid
• State: /tmp/telegram_listener_state.json
• Logs: logs/telegram_listener.log
• Queue: /tmp/telegram_agent_queue.json
• Template: templates/helper_template.py

Config (user_profile.json → telegram)

{ "chat_id": null, "notifications_enabled": true, "morning_brief": true,
  "task_reminders": true, "goal_checkin_time": "20:00", "always_listening": true }

Building New Integrations

Use the telegram-builder skill for detailed guidance on adding new commands and services.

Quick Pattern

1. Add helper function in telegram_helpers.py:

   def get_my_service(query=None):
       """Fetch data from your API."""
       # Your implementation
       return "**My Service**\nResult here"

1. Import in telegram_listener.py:

   from telegram_helpers import get_my_service

1. Add command handler in route_command():

   if lower.startswith("/myservice"):
       query = text.split(maxsplit=1)[1] if len(text.split()) > 1 else None
       return get_my_service(query)

Template Reference

See templates/helper_template.py for a complete integration example.

Built-in Bot Commands

The user can send these commands directly to their bot:

Tasks & Goals

System

Scheduled Alerts

Configured in user_profile.json → telegram: