tg-alerts

name: tg-alerts description: Use when adding Telegram error notifications to any project. Guides through bot creation with @BotFather, chat/channel/forum-topic ID discovery, alert service implementation with deduplication and graceful failure, and framework-specific integration for Python (async/sync) and Node.js.

Telegram Error Alerts

Adds operational error alerts to any project via a dedicated Telegram bot. Alerts go to a private channel, group, or forum topic — not to end users. Battle-tested pattern with deduplication, HTML formatting, and crash-proof error handling.

When to Use

• User asks to add error notifications, Telegram alerts, or operational monitoring
• Setting up a new deployment and want to know when things break
• NOT for: user-facing bot messages or interactive Telegram features

Setup Flow

This skill is interactive. Each phase involves asking the user questions or guiding them through Telegram actions.

digraph flow {
    rankdir=LR;
    "Assess\nProject" -> "Create\nBot" -> "Get\nChat ID" -> "Generate\nCode" -> "Integrate" -> "Test";
}

Phase 1: Assess Project

Detect from codebase or ASK:

1. Language — Python / Node.js / TypeScript / other
2. Framework — FastAPI, Django, Flask, Express, NestJS, Hono, etc.
3. Async or sync — determines implementation variant
4. Already has a Telegram bot? — alert bot MUST be separate from any main bot

Phase 2: Create Alert Bot

Guide the user through these Telegram steps:

1. Open Telegram, find @BotFather
2. Send /newbot
3. Name: something like "MyApp Alerts"
4. Username: something like myapp_alerts_bot
5. BotFather replies with a token — copy it
6. Save as ALERT_BOT_TOKEN in .env

ASK the user to confirm they have the token before proceeding.

Phase 3: Get Chat ID

ASK: "Where should alerts go?"

Guide based on their choice:

Option A: Private Chat

1. Open Telegram, find your new alert bot
2. Send it any message (e.g., "hello")
3. Run in terminal:

curl -s "https://api.telegram.org/bot<YOUR_TOKEN>/getUpdates" | python3 -m json.tool

4. Find "chat": {"id": 123456789} — that positive number is your ALERT_CHAT_ID

Option B: Group

1. Create a Telegram group (or use existing)
2. Add the alert bot to the group
3. Send any message in the group
4. Run the getUpdates curl above
5. Find chat.id — negative number like -1001234567890

Option C: Channel

1. Create a channel (or use existing)
2. Add the alert bot as administrator (needs "Post Messages" permission)
3. Post any message in the channel
4. Run getUpdates
5. Find "channel_post" -> "chat" -> "id" — negative, starts with -100

Option D: Forum Topic

1. Create a group -> Settings -> enable Topics
2. Add the bot to the group
3. Create a topic (e.g., "Errors")
4. Send a message inside that topic
5. Run getUpdates
6. Find TWO values:
   • chat.id -> ALERT_CHAT_ID
   • message_thread_id -> ALERT_THREAD_ID

Verify IDs

Always test before writing code:

curl -s -X POST "https://api.telegram.org/bot<TOKEN>/sendMessage" \
  -d chat_id=<CHAT_ID> -d "text=Test alert" -d parse_mode=HTML

For forum topics, add -d message_thread_id=<THREAD_ID>.

If the message appears in Telegram, proceed to Phase 4.

Troubleshooting empty getUpdates:

• Send another message, then run curl immediately (updates expire)
• For channels: bot must be admin, not just member
• For groups: send /setprivacy to @BotFather -> set to Disabled

Phase 4: Generate Alert Service

Use the appropriate reference implementation from this skill's directory:

Read the reference file and adapt to the project:

• Match code style, naming conventions, import patterns
• Use the project's existing HTTP client if available
• Place where services/utils live in the project structure
• Add env vars to the project's config system

Phase 5: Framework Integration

Wire alert service into the project's error handling. The pattern:

1. Initialize on startup (only if env vars present)
2. Attach logging handler to root logger (captures all logger.error() / console.error())
3. Add unhandled exception handler specific to the framework
4. Send lifecycle alert on startup and shutdown

Phase 6: Environment Variables

Add to .env and .env.example:

# Telegram operational alerts (optional)
# ALERT_BOT_TOKEN=123456:ABC-DEF...
# ALERT_CHAT_ID=-1001234567890
# ALERT_THREAD_ID=42

Ensure the config treats these as optional — alerting gracefully disables when not configured:

alerting_enabled = bool(ALERT_BOT_TOKEN and ALERT_CHAT_ID)

Phase 7: Test

1. Start the app with alert env vars set
2. Check for startup lifecycle alert in Telegram
3. Trigger an intentional error (e.g., hit a broken endpoint)
4. Verify error alert appears with traceback
5. Trigger same error again — verify dedup blocks the duplicate
6. Stop the app — verify shutdown alert

Alert Message Format

Consistent across all stacks — use Telegram HTML parse mode:

🔴 <b>Error</b>
<pre>Env: production
Error: ValueError
Context: [module.name] error message

Traceback (most recent call last):
  ...</pre>

🟡 <b>Warning</b>
<pre>Env: production
Some warning message</pre>

🟢
<pre>Application started
Env: production</pre>

Critical Design Rules

Non-negotiable for every implementation:

1. Alert failures NEVER crash the app — wrap all sending in try/except or try/catch
2. Log alert failures at DEBUG — ERROR would trigger the handler again -> infinite loop
3. Deduplicate by exception location — key: {ExcType}:{lineno}@{filename}. One alert per crash site
4. Truncate to 3500 chars — Telegram limit is 4096; stay well under
5. HTML-escape all dynamic content — tracebacks contain <>& breaking Telegram HTML
6. Separate bot — never reuse the main app bot for alerts
7. Include environment — every alert shows dev/staging/prod
8. Make alerting optional — app runs normally without alert env vars
9. Fire-and-forget — async: create_task(), sync: daemon thread. Never block requests
10. Cap dedup set at ~10k — clear when full to prevent unbounded memory growth

Common Mistakes