DEV Community

Chalom Ellezam
Chalom Ellezam

Posted on

Telegram alerts for any production app — a 5-minute setup (no SaaS, no signup, just curl)

#monitoring #devops #webdev #tutorial

Disclosure: I'm a senior backend tech lead and I run HostingGuru, where Telegram alerts ship as a built-in feature. This tutorial works on any platform — it's the manual version of what HostingGuru does for you. Useful even if you never become a customer.

There's a hierarchy of where production alerts go, ranked by how likely you are to actually see them.

  1. Email → 14% open rate within an hour, less at 3am.
  2. Slack → muted in 6 of 10 teams I've seen, especially "alerts" channels.
  3. Phone-call paging (PagerDuty, Opsgenie) → works, but $20+/user/month and overkill for solo founders.
  4. Telegram → notification on lock screen, no setup cost, works on every phone, you'll see it.

For a solo founder or a small team, Telegram alerts hit a sweet spot: the notification is annoying enough that you'll see it, easy enough that you'll set it up, and free. After 8 years of trying every paging tool, this is what I default to for early-stage projects.

Here's how to wire it up in 5 minutes, plus what I learned about what to alert on.

Step 1: Create a Telegram bot (60 seconds)

  1. Open Telegram, search for @BotFather, start a chat.
  2. Send /newbot.
  3. Pick a name. Then a username (must end in bot, e.g. myapp_alerts_bot).
  4. BotFather replies with a token like 7234567890:AAFq.... Save it. This is your TELEGRAM_BOT_TOKEN.

That's it. The bot exists. Now we need somewhere to send messages.

Step 2: Get your chat ID (60 seconds)

You need the ID of the chat where alerts will land. Two options:

Option A — Personal alerts (just for you):

  1. Open a chat with your new bot. Send it any message ("hello").
  2. Visit https://api.telegram.org/bot<YOUR_TOKEN>/getUpdates in your browser.
  3. Find the chat.id field in the JSON response. It's a number like 123456789. That's your chat ID.

Option B — Group alerts (for the team):

  1. Create a Telegram group (or use an existing one).
  2. Add your bot to the group.
  3. Send any message in the group.
  4. Visit the same getUpdates URL. The chat ID for groups is negative (e.g. -987654321).

Save the chat ID as TELEGRAM_CHAT_ID.

Step 3: Send your first alert (30 seconds)

The send API is one HTTP call. From a terminal:

curl -s -X POST \
  "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/sendMessage" \
  -d "chat_id=${TELEGRAM_CHAT_ID}" \
  -d "text=Hello from production"
Enter fullscreen mode Exit fullscreen mode

Your phone should buzz immediately. If it does, the wiring is done. Now we just need to call this from your app when something interesting happens.

Step 4: Wire it into your app (3 minutes)

Node.js / TypeScript 

// alerts.ts
const TG_TOKEN = process.env.TELEGRAM_BOT_TOKEN!;
const TG_CHAT  = process.env.TELEGRAM_CHAT_ID!;

export async function alert(message: string) {
  if (!TG_TOKEN || !TG_CHAT) return; // disabled in dev
  try {
    await fetch(`https://api.telegram.org/bot${TG_TOKEN}/sendMessage`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        chat_id: TG_CHAT,
        text: message.slice(0, 4000), // Telegram cap
        parse_mode: 'Markdown',
      }),
    });
  } catch (e) {
    // never let alerting crash your app
    console.error('alert failed', e);
  }
}
Enter fullscreen mode Exit fullscreen mode

Use it anywhere:

import { alert } from './alerts';

process.on('uncaughtException', (err) => {
  alert(`🚨 *Uncaught exception*\n\`${err.message}\`\n\nstack:\n\`\`\`\n${err.stack}\n\`\`\``);
});

// or in business logic
if (failed > THRESHOLD) {
  await alert(`⚠️ Stripe webhook retry rate at ${failed}/min — investigate`);
}
Enter fullscreen mode Exit fullscreen mode

Python 

# alerts.py
import os
import requests

TG_TOKEN = os.environ.get('TELEGRAM_BOT_TOKEN')
TG_CHAT  = os.environ.get('TELEGRAM_CHAT_ID')

def alert(message: str) -> None:
    if not TG_TOKEN or not TG_CHAT:
        return
    try:
        requests.post(
            f'https://api.telegram.org/bot{TG_TOKEN}/sendMessage',
            json={
                'chat_id': TG_CHAT,
                'text': message[:4000],
                'parse_mode': 'Markdown',
            },
            timeout=5,
        )
    except Exception as e:
        # never let alerting crash your app
        print(f'alert failed: {e}')
Enter fullscreen mode Exit fullscreen mode

Wire it to the unhandled exception hook:

import sys
from alerts import alert

def excepthook(exc_type, exc_value, exc_traceback):
    alert(f'🚨 *Uncaught exception*\n`{exc_type.__name__}: {exc_value}`')
    sys.__excepthook__(exc_type, exc_value, exc_traceback)

sys.excepthook = excepthook
Enter fullscreen mode Exit fullscreen mode

Plain bash (great for cron jobs) 

#!/usr/bin/env bash
# Save as /usr/local/bin/tg-alert
curl -s -X POST \
  "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/sendMessage" \
  --data-urlencode "chat_id=${TELEGRAM_CHAT_ID}" \
  --data-urlencode "text=$1" > /dev/null
Enter fullscreen mode Exit fullscreen mode

Then any cron job can do:

0 3 * * * /opt/myapp/nightly-backup.sh || tg-alert "❌ Nightly backup failed at $(hostname)"
Enter fullscreen mode Exit fullscreen mode

That's the whole infrastructure. You're done.

Step 5: The rate-limiting trick (the part most tutorials skip)

Here's the failure mode of every "I just wired alerts" project: a bug fires at 200/sec, your phone buzzes 200 times in 10 seconds, you mute the bot in frustration, you miss the next real alert two days later.

You need a rate limiter between your code and Telegram. The simplest one: deduplicate identical messages within a window.

Node.js — in-memory dedupe 

const seen = new Map<string, number>();
const DEDUPE_WINDOW_MS = 5 * 60 * 1000; // 5 minutes

export async function alert(message: string) {
  const key = message.slice(0, 200); // use first 200 chars as dedupe key
  const last = seen.get(key);
  if (last && Date.now() - last < DEDUPE_WINDOW_MS) return; // skip
  seen.set(key, Date.now());

  // ... rest of the send logic
}
Enter fullscreen mode Exit fullscreen mode

This means the same alert won't fire more than once every 5 minutes, but different alerts still go through. A retry loop firing the same exception 800 times in 10 minutes will produce 3 Telegram messages, not 800. You'll still know it's happening.

Redis-backed (for multi-instance apps)

If your app runs on multiple servers, in-memory dedupe doesn't work. Use Redis:

import Redis from 'ioredis';
const redis = new Redis(process.env.REDIS_URL!);

export async function alert(message: string) {
  const key = `tg-dedupe:${hash(message.slice(0, 200))}`;
  const set = await redis.set(key, '1', 'EX', 300, 'NX');
  if (set !== 'OK') return; // already alerted in last 5 min

  // ... send to Telegram
}
Enter fullscreen mode Exit fullscreen mode

The EX 300 NX does the magic: set the key with a 5-minute TTL, but only if it doesn't already exist. If two servers try to send the same alert simultaneously, only one wins.

What to alert on (the harder question)

The tutorial above is the easy part. The hard part is what to alert on. Bad alerts → alert fatigue → muted bot → you miss the real ones.

Five things that are usually worth a Telegram ping:

  1. Uncaught exceptions in the main process — these usually mean a process is about to die or has died.
  2. Job queue depth above N — if Sidekiq/BullMQ/Celery has more than e.g. 1000 jobs queued, something is producing faster than consuming. Investigate.
  3. 5xx error rate above 1% — not every 500 needs a ping, but the rate exceeding a threshold does.
  4. Specific business events that mean money is leaking — failed payment retries, stale webhook signatures, expired refresh tokens.
  5. Cron jobs that didn't run — if your nightly backup didn't fire by 3:30am, you want to know at 3:30am, not at 9am when you check email.

Five things that are usually NOT worth a ping:

  1. Individual 4xx errors (these are mostly user error or scrapers).
  2. Slow queries (log them, don't page on them).
  3. Anything you can't act on in the next 30 minutes.
  4. Anything where the action is "do nothing, it'll resolve itself" (most CDN hiccups, most rate-limit blips).
  5. Anything informational ("user X signed up" — use a different channel for celebration).

The test I use: if I'm at dinner and my phone buzzes, will I be glad I knew, or annoyed? If the answer is "annoyed," it doesn't belong on Telegram.

A note on alert resolution

A subtle thing most tutorials skip: alerts should also tell you when something is fixed. If your job queue depth crossed 1000 and you got pinged, you also want a "now back to 0" ping when it normalizes. Otherwise you spend 20 minutes manually checking the dashboard.

The simplest pattern:

let inAlertState = false;

export async function checkQueueDepth(depth: number) {
  if (depth > 1000 && !inAlertState) {
    await alert(`🔴 Queue depth: ${depth}`);
    inAlertState = true;
  }
  if (depth < 100 && inAlertState) {
    await alert(`🟢 Queue back to ${depth}`);
    inAlertState = false;
  }
}
Enter fullscreen mode Exit fullscreen mode

Two messages per incident, not 200. Your bot stays usable.

When to stop building this and use a platform

Everything above takes about an evening to wire up properly. For a small team, that's a great trade.

There are three signs it's time to stop building this and use a platform that does it:

  1. You're spending more than 1 day a quarter maintaining your alerting setup.
  2. You realize you need pattern detection (retry loops, token spikes, anomalous response times) — those are much harder to write yourself than threshold alerts.
  3. You've muted your own bot more than once.

That's the gap HostingGuru fills. The platform tails your production logs, runs pattern detection automatically (retry loops, token spikes, hot fingerprints, anomalous latency, silent cron failures), and pings you on Telegram with a link to the relevant logs. No code in your app, no Redis dedupe to maintain — it's part of the hosting layer. €19/mo Hobby, €35/mo Pro.

If you're already deployed somewhere else, the homemade Telegram setup above is a fine start — and probably better than no alerts at all.

What to do after you finish reading this

Concretely, in the next 30 minutes:

  1. Create the bot via BotFather.
  2. Get your chat ID with getUpdates.
  3. Add TELEGRAM_BOT_TOKEN and TELEGRAM_CHAT_ID to your env vars on whatever platform you use.
  4. Drop the alert(message) helper into your codebase.
  5. Wire it to your top-level uncaught exception handler.
  6. Add the dedupe logic so a runaway loop doesn't spam you.

That's the minimum viable production alerting setup for any app. It costs $0, works in any country, lives on your phone, and survives every channel rotation in your team.

If you wire something interesting on top of this — anomaly detection, business event alerts, anything cool — drop it in the comments. I'm always looking for new patterns to steal.

Previous posts in this series:

1. Heroku just went into "sustaining engineering mode." Here are 5 alternatives whose free tier actually doesn't sleep

2. I built my MVP with Claude Code. Now I need to deploy it. Here's what nobody tells you.

3. Your AI app is silently burning $2,000/month and you don't know it. Here are the 5 patterns that bite founders.

Top comments (0)