Pre-flight Telegram Auditor

Validates Telegram bot token and chat ID configuration before sending notifications, ensuring delivery will succeed.

When to Use This Hook

Attach this hook when you need to:

• Verify Telegram bot credentials and chat ID are valid before critical operations that depend on notification delivery
• Audit bot permissions in the target chat to ensure the bot can send messages, preventing silent delivery failures
• Pre-validate API connectivity to the Telegram Bot API before executing deployment or build commands

Consider alternatives when:

• Your Telegram bot configuration is stable and you prefer to handle delivery failures reactively rather than with pre-flight checks
• You use a notification aggregation service that handles Telegram delivery with its own retry and validation logic

Quick Start

Configuration

Copy
name: pre-flight-telegram-auditor
type: hook
trigger: PreToolUse
category: automation

Example Trigger

Copy
git push origin main
# Hook fires before push:
# Pre-flight: Validating Telegram bot configuration...

Example Output

Pre-flight Telegram Audit:
Bot Token: Configured (TELEGRAM_BOT_TOKEN set)
Chat ID: Configured (TELEGRAM_CHAT_ID set)
Bot API Test: 200 OK - Bot "ClaudeNotifier" active
Chat Access: Verified - bot can send to chat -1001234567
Rate Limit: No recent throttling detected
Audit Log: Entry recorded at 2026-03-15T14:23:07Z
Status: READY - Telegram notifications will be delivered

Core Concepts

Telegram Audit Overview

Aspect	Details
Trigger Point	PreToolUse before Bash commands matching deploy/push patterns
Bot Validation	Calls getMe API to verify bot token is valid and active
Chat Validation	Calls getChat API to verify bot has access to target chat
Required Variables	TELEGRAM_BOT_TOKEN and TELEGRAM_CHAT_ID environment variables
Cache Duration	Successful validation cached for 10 minutes between checks
Failure Mode	Warns on validation failure but does not block command execution

Audit Workflow

PreToolUse Triggered
    |
    v
[Match deploy/push command pattern?]
    |          |
   No         Yes
    |          |
 [Skip]       v
         [Check TELEGRAM_BOT_TOKEN and TELEGRAM_CHAT_ID set?]
              |          |
          Missing       Set
              |          |
           [Warn]       v
                   [Cache valid? (< 10 min)]
                        |          |
                       Yes        No
                        |          |
                     [Skip]       v
                             [Call getMe API to verify bot]
                                  |
                                  v
                             [Call getChat to verify access]
                                  |
                            +-----+-----+
                            |           |
                          Valid      Invalid
                            |           |
                         [Log OK]    [Log failure + warn]

Configuration

Parameter	Type	Default	Description
TELEGRAM_BOT_TOKEN	string	(required)	Bot token obtained from @BotFather on Telegram
TELEGRAM_CHAT_ID	string	(required)	Target chat, group, or channel ID for notifications
command_patterns	string	push|deploy|release	Regex pattern for commands that trigger pre-flight validation
cache_ttl	integer	600	Seconds to cache successful validation before re-checking
audit_log_path	string	.claude/telegram-audit.log	File path for the validation audit trail

Best Practices

1. Obtain the chat ID correctly - After creating a bot with @BotFather and sending it a message, visit https://api.telegram.org/bot<TOKEN>/getUpdates to find your chat ID. Group chat IDs are negative numbers and channel IDs start with -100. Incorrect chat ID format is the most common setup error.

2. Use a dedicated bot for Claude Code notifications - Create a separate Telegram bot specifically for Claude Code notifications rather than reusing a bot with other responsibilities. This makes it easy to manage permissions and review notification history.

3. Test bot permissions in group chats - If sending to a group, the bot must be a member of the group with permission to send messages. Bots added to groups after the group privacy setting was enabled may not receive context about the group. Verify permissions using the getChat API.

4. Store credentials in environment files - Export TELEGRAM_BOT_TOKEN and TELEGRAM_CHAT_ID in your shell profile or .env file. Never hardcode these values in hook configuration files that may be committed to version control.

5. Monitor audit logs for intermittent failures - Telegram API connectivity can be inconsistent in some network environments. Review the audit log to identify patterns such as failures during specific hours or from specific network locations.

Common Issues

1. Bot token validation fails with 401 Unauthorized - The bot token is incorrect or the bot has been deleted by @BotFather. Verify the token by visiting https://api.telegram.org/bot<TOKEN>/getMe in a browser. If invalid, create a new bot or regenerate the token with @BotFather.

2. Chat ID returns "chat not found" error - The bot has not been added to the target chat, or the chat ID format is wrong. For private chats, send a message to the bot first. For groups, add the bot as a member. For channels, add the bot as an administrator.

3. Audit cache causes missed configuration changes - If you change the bot token or chat ID while a cached validation is active, the auditor will not detect the change until the cache expires. Clear the cache manually by deleting the cache file or restart the session to force re-validation.