telegram-doctor_skill

Overview

This skill diagnoses Telegram configuration and connectivity issues for integrations that sync messages or use the Telegram API. It runs a series of non-destructive checks and reports which items pass or fail, with targeted suggested fixes. Use it as a first step before making changes or asking for support.

How this skill works

The tool inspects the local environment and configuration files: it checks for a .env file, validates TELEGRAM_API_ID and TELEGRAM_API_HASH, verifies the session string length, and confirms the app can authenticate with Telegram. It also validates config/agents.yaml, ensures a default group is configured, and checks that the data/ directory is present and writable. Results are shown with pass/fail marks and concise suggested remediation steps; the tool does not modify any files.

When to use it

• User reports "Telegram not working" or sync failures
• Connection or authentication errors appear in logs
• Preparing to run telegram-sync or telegram-init
• Before filing an issue or requesting help
• After moving the project or changing environment variables

Best practices

• Keep a copy of your .env before editing environment variables
• Use numeric API ID and exact API hash from your Telegram app settings
• Keep session strings secure and regenerate if they appear truncated
• Run telegram-doctor immediately after changing config files or upgrading dependencies
• Follow suggested fixes exactly and re-run the doctor to confirm fixes

Example use cases

• Diagnose a failed telegram-sync that reports authentication errors
• Confirm environment variables and file permissions on a fresh deployment
• Validate that a default Telegram group is selected before starting a continuous sync
• Check whether the session string was corrupted or truncated
• Run quick preflight checks as part of a troubleshooting checklist