Telegram Doctor

Diagnose configuration and connectivity issues with Telegram integration.

When to Use

• User says “Telegram not working” or “diagnose Telegram”
• User reports connection or authentication errors
• User says “check Telegram setup” or “troubleshoot Telegram”
• Before asking for help with Telegram issues
• When sync or other Telegram commands fail unexpectedly

How to Execute

python ${CLAUDE_PLUGIN_ROOT}/tools/telegram_doctor.py

What It Checks

1. Environment file – .env exists in cwd
2. API ID – TELEGRAM_API_ID is set and numeric
3. API hash – TELEGRAM_API_HASH is set
4. Session string – TELEGRAM_SESSION is set and valid length
5. Authentication – Credentials can connect to Telegram API
6. Config file – config/agents.yaml exists and is valid YAML
7. Group configured – A default group is selected
8. Data directory – data/ is writable

Output

Displays results with:

• ✓ for passed checks
• ✗ for failed checks

For each failure, provides a suggested fix that the user can run manually.

Important: This tool only diagnoses issues – it does not modify any files.

Example Output

telegram-doctor results:

  ✓ Environment file (.env found)
  ✓ API ID (12345678)
  ✓ API hash (abc123...xyz9)
  ✗ Session string (Session appears too short)
  ✗ Config file (config/agents.yaml not found)
  ✗ Group configured (No default group set)
  ✓ Data directory (./data)

Some checks failed. Suggested fixes:

  • Session string:
    Generate a fresh session: python scripts/generate_session.py

  • Config file:
    Run telegram-init to create the config file

  • Group configured:
    Run telegram-init to select a group

(Run these steps manually - doctor does not modify files)

Next Steps

After fixing issues:

1. Run telegram-init to reconfigure if needed
2. Run telegram-sync to test connectivity