Telegram Notifications Hook

Sends Telegram messages when Claude Code sessions end or subagent tasks complete, using the Telegram Bot API for delivery.

When to Use This Hook

Attach this hook when you need to:

• Receive instant Telegram notifications when Claude Code finishes processing so you can review results without watching the terminal
• Monitor subagent task completions in addition to main session endings for comprehensive session lifecycle visibility
• Use Telegram as a lightweight, mobile-friendly notification channel that works across all devices without desktop access

Consider alternatives when:

• Your team communication is centralized on Slack or Discord and adding Telegram creates channel fragmentation
• You need rich formatted notifications with embeds, images, or interactive buttons that Telegram plain text messages do not support

Quick Start

Configuration

Copy
name: telegram-notifications-hook
type: hook
trigger: Stop, SubagentStop
category: automation

Example Trigger

Copy
# Claude Code session ends naturally:
# Telegram message: "Claude Code finished working at 2026-03-15 14:23:07"
# Subagent completes a task:
# Telegram message: "Claude Code subagent completed task at 2026-03-15 14:25:12"

Example Output

Telegram Notification Sent:
Bot: ClaudeNotifier
Chat: -1001234567
Message: Claude Code finished working at 2026-03-15 14:23:07
Parse Mode: HTML
Delivery: Success (message_id: 4521)

[On subagent completion]
Telegram Notification Sent:
Bot: ClaudeNotifier
Chat: -1001234567
Message: Claude Code subagent completed task at 2026-03-15 14:25:12

Core Concepts

Telegram Notification Overview

Aspect	Details
Events Tracked	Stop (main session ends) and SubagentStop (subagent task completes)
API Endpoint	https://api.telegram.org/bot<TOKEN>/sendMessage
Required Variables	TELEGRAM_BOT_TOKEN and TELEGRAM_CHAT_ID environment variables
Message Format	HTML parse mode for basic formatting support
Bot Setup	Create bot via @BotFather, get chat ID from getUpdates API
Failure Handling	Prints error message to stderr if delivery fails

Notification Delivery Workflow

Stop or SubagentStop Event
    |
    v
[Check TELEGRAM_BOT_TOKEN and TELEGRAM_CHAT_ID set?]
    |                    |
  Missing               Set
    |                    |
    v                    v
[Print warning]    [Compose message with timestamp]
                        |
                        v
                   [POST to Telegram sendMessage API]
                        |
                  +-----+-----+
                  |           |
               Success     Failure
                  |           |
               [Silent]    [Print error to stderr]

Configuration

Parameter	Type	Default	Description
TELEGRAM_BOT_TOKEN	string	(required)	Bot authentication token from @BotFather
TELEGRAM_CHAT_ID	string	(required)	Target chat, group, or channel ID for message delivery
parse_mode	string	HTML	Message parsing mode: HTML or Markdown for text formatting
include_project	boolean	false	Whether to include the project directory name in the notification
disable_notification	boolean	false	Send message silently without triggering a device notification sound

Best Practices

1. Set up the bot correctly with @BotFather - Create a new bot, save the token securely, and send the bot a message to initialize the chat. Visit https://api.telegram.org/bot<TOKEN>/getUpdates to find your chat ID. This setup only needs to be done once per bot.

2. Use group chats for team visibility - Instead of sending notifications to a private chat, create a Telegram group and add the bot. This allows the entire team to see session completion notifications. Remember that group chat IDs are negative numbers.

3. Enable subagent notifications for complex workflows - The SubagentStop event fires when Claude Code delegates tasks to subagents. Enabling notifications for both Stop and SubagentStop ensures you are informed of all work completion events, not just the final session end.

4. Include project context in messages - The default message only includes a timestamp. Customize the message template to include the project directory name, making it easy to identify which project a notification belongs to when you receive alerts from multiple repositories.

5. Use silent mode during working hours - Set disable_notification to true during focused work periods. Messages will still appear in the chat but without triggering a sound or vibration on your device, reducing interruptions while maintaining visibility.

Common Issues

1. Notifications not delivered despite tokens being set - The bot must have initiated contact with the chat. For private chats, you must send a message to the bot first. For groups, add the bot as a member. Verify by calling the getUpdates API to confirm the bot can see the chat.

2. HTML parse mode causes message delivery failure - If the notification message contains unescaped HTML characters like <, >, or &, the Telegram API will reject the message. Ensure the message content escapes these characters or switch to plain text mode by removing the parse_mode parameter.

3. SubagentStop notifications not firing - The SubagentStop event only triggers when Claude Code uses subagents for task delegation. If your workflow does not involve subagents, this event will never fire. This is expected behavior; the Stop event alone provides session-end notifications.