Automated Telegram Inspector

Inspects and reports Telegram notification delivery status after each message, tracking delivery success rates and API response metrics.

When to Use This Hook

Attach this hook when you need to:

• Monitor Telegram notification delivery success rates across sessions to ensure reliable message delivery over time
• Automatically log Telegram API responses for debugging delivery failures and identifying intermittent connectivity issues
• Generate delivery reports that track which notifications were successfully received versus which failed silently

Consider alternatives when:

• You send Telegram notifications infrequently and manual verification of delivery is sufficient for your workflow
• Your Telegram bot has built-in delivery confirmation via read receipts that you already monitor

Quick Start

Configuration

Copy
name: automated-telegram-inspector
type: hook
trigger: PostToolUse
category: automation

Example Trigger

Copy
# After a Bash command that sends a Telegram notification:
curl -X POST "https://api.telegram.org/bot.../sendMessage" -d "..."
# Inspector checks delivery status:

Example Output

Telegram Inspector: Delivery Report
Last Message: Delivered successfully
Message ID: 4521
Chat: my-project-notifications (-1001234567)
API Response Time: 187ms
Daily Delivery Stats:
  Sent: 23
  Delivered: 22
  Failed: 1 (retry scheduled)
Success Rate: 95.7%
Status: HEALTHY

Core Concepts

Inspection Overview

Aspect	Details
Trigger Point	PostToolUse after Bash commands containing Telegram API calls
Metrics Tracked	Delivery status, response time, message ID, success rate
History File	.claude/telegram-delivery.json stores delivery metrics
Alert Threshold	Success rate below 90% triggers a degradation warning
Retry Logic	Failed deliveries are logged for manual retry or automatic reattempt
API Parsing	Extracts message_id and ok status from Telegram API responses

Inspection Workflow

PostToolUse (Bash with Telegram API call)
    |
    v
[Parse API response from command output]
    |
    v
[Extract: ok, message_id, response time]
    |
    v
[Update delivery history JSON]
    |
    v
[Calculate session success rate]
    |
    v
[Success rate < 90%?]
    |           |
   No          Yes
    |           |
    v           v
[Log OK]    [Output degradation warning]

Configuration

Parameter	Type	Default	Description
history_file	string	.claude/telegram-delivery.json	Path to store delivery metrics and history
success_threshold	integer	90	Percentage success rate below which a degradation warning is shown
max_history_entries	integer	100	Maximum number of delivery records to retain in the history file
include_response_body	boolean	false	Whether to log full API response bodies for debugging
retry_failed	boolean	false	Whether to automatically retry failed deliveries on the next hook trigger

Best Practices

1. Review delivery stats at session end - Check the delivery report at the end of each session to confirm all notifications were received. A 100% success rate confirms reliable connectivity, while any failures warrant investigation before they become persistent.

2. Correlate failures with network changes - If delivery failures cluster around specific times or after VPN connections change, the issue is likely network-related rather than configuration-related. Log the network interface state alongside delivery metrics for correlation.

3. Set appropriate history retention limits - The default 100-entry limit prevents the history file from growing unbounded. For long-running sessions with many notifications, increase this limit. For infrequent notification use, reduce it to keep the file small.

4. Use the inspector alongside the pre-flight auditor - The pre-flight auditor validates configuration before sending, while the inspector verifies delivery after sending. Together they provide complete coverage of the notification lifecycle.

5. Archive delivery reports for compliance - If your team requires notification delivery records for compliance or auditing purposes, configure the inspector to write delivery reports to a persistent log file rather than the rotating history JSON.

Common Issues

1. Inspector does not detect Telegram API calls - The inspector uses pattern matching on Bash command output to identify Telegram API calls. If your notification commands redirect output to /dev/null, the inspector cannot parse the API response. Capture stdout while still suppressing terminal output.

2. Success rate drops suddenly without configuration changes - Telegram API rate limits may throttle your bot if it sends too many messages in a short period. Bots are limited to approximately 30 messages per second. Space out notifications or batch them to stay within limits.

3. History file grows too large and slows hook execution - If max_history_entries is set too high or not enforced, the JSON file can grow large enough to impact hook performance. Verify the entry limit is configured and working, and manually truncate the file if it has already grown excessively.