uptime-telegram 🔔

"If your site goes down — Telegram calls you before your first user does."

The Problem

uptime-robot sends email. Email is checked hours later. 3 hours of downtime = thousands in lost revenue.

Every SaaS founder has lived this nightmare: wake up, check email, find an alert sent at 2 AM saying your site has been down for 3 hours. Three hours of silent failure — lost signups, failed payments, abandoned carts, and angry users who'll never come back.

The problem isn't the monitoring tool. The problem is the notification channel. Email is cold and slow. No one reads it at 3 AM.

uptime-telegram solves exactly one problem with surgical precision: Know in second zero that your site is down — via the only channel guaranteed to wake you up: Telegram.

Features

| Feature | Free | Pro ($9/mo) | |---------|------|-------------| | Monitored sites | 3 | Unlimited | | Check interval | 60s min | 10s min | | Telegram Bot alerts | ✅ | ✅ | | Voice alerts (voice note) | ❌ | ✅ | | SMS via Twilio | ❌ | ✅ | | Recovery notifications | ✅ | ✅ | | Uptime % tracking | ✅ | ✅ | | Incident history | Last 10 | Unlimited | | Web dashboard | ❌ | ✅ | | Redis storage | ❌ | ✅ | | CLI tool | ✅ | ✅ | | Custom headers | ✅ | ✅ | | Content checking | ✅ | ✅ | | SSL expiry alerts | ❌ | ✅ |

Installation

npm install uptime-telegram

For global CLI usage:

npm install -g uptime-telegram

Quick Start

Minimal Setup (30 seconds)

import uptimeTelegram from 'uptime-telegram';

uptimeTelegram.configure({
  telegram: {
    token: process.env.TELEGRAM_BOT_TOKEN!,
    chatId: process.env.TELEGRAM_CHAT_ID!,
  },
});

uptimeTelegram.monitor('https://myapp.com');

Full Setup with All Features

import uptimeTelegram from 'uptime-telegram';

uptimeTelegram.configure({
  telegram: {
    token: process.env.TELEGRAM_BOT_TOKEN!,
    chatId: process.env.TELEGRAM_CHAT_ID!,
  },
  sms: {
    accountSid: process.env.TWILIO_ACCOUNT_SID!,
    authToken:  process.env.TWILIO_AUTH_TOKEN!,
    from:       process.env.TWILIO_FROM_NUMBER!,
    to:         process.env.ALERT_SMS_TO!,
  },
  storage: { backend: 'file', filePath: './uptime-state.json' },
  logging: { level: 'info' },
});

// Monitor with full options
const monitor = uptimeTelegram.monitor('https://myapp.com', {
  check:             '10s',
  call:              true,           // voice alert on Telegram
  sms:               true,           // SMS fallback
  timeout:           8000,
  failureThreshold:  2,
  recoveryThreshold: 1,
  expectedStatus:    [200, 201],
  expectedContent:   '"status":"ok"',
  headers:           { 'X-Monitor': 'uptime-telegram' },
});

// Listen to events
monitor.on('down',     (data) => console.error('🔴 DOWN!', data.url));
monitor.on('up',       (data) => console.log('🟢 RECOVERED!', data.url));
monitor.on('check',    (data) => console.log('✅ check', data.result.latency + 'ms'));
monitor.on('incident', (data) => console.log('📋 Incident:', data));

CLI Usage

# Start monitoring immediately
uptime-telegram start \
  --url myapp.com \
  --token "YOUR_BOT_TOKEN" \
  --chat-id "YOUR_CHAT_ID" \
  --check 30s \
  --call

# Check status
uptime-telegram status

# Add another site
uptime-telegram add https://api.myapp.com

# Remove a site
uptime-telegram remove https://api.myapp.com

# Open dashboard
uptime-telegram dashboard --port 3001

Telegram Bot Setup (2 minutes)

Step 1: Create your bot

1. Open Telegram → search for @BotFather
2. Send /newbot
3. Choose a name: MyApp Uptime Bot
4. Choose a username: myapp_uptime_bot
5. Copy the token (looks like 7123456789:AABBccdd...)

Step 2: Get your Chat ID

1. Open a conversation with your new bot
2. Send any message (e.g., /start)
3. Visit: https://api.telegram.org/bot{YOUR_TOKEN}/getUpdates
4. Look for "chat":{"id": 123456789} — that's your Chat ID

Step 3: Configure

cp .env.example .env
# Edit .env with your token and chat ID

Configuration Reference

uptimeTelegram.configure({
  // ─── Telegram (Required) ───────────────────────────────────
  telegram: {
    token:  string;  // Bot token from BotFather
    chatId: string | number;  // Your chat/group/channel ID
  };

  // ─── SMS via Twilio (Optional) ─────────────────────────────
  sms?: {
    accountSid: string;
    authToken:  string;
    from:       string;  // Twilio phone number
    to:         string;  // Your phone number
  };

  // ─── Voice / TTS (Optional) ────────────────────────────────
  ttsApiKey?:           string;  // Google TTS API key
  callRepeat?:          number;  // How many times to repeat alert (default: 3)
  callRepeatInterval?:  number;  // ms between repeats (default: 60000)

  // ─── Storage (Optional) ────────────────────────────────────
  storage?: {
    backend:   'memory' | 'file' | 'redis';
    filePath?: string;  // For file backend
    redisUrl?: string;  // For Redis backend
  };

  // ─── Logging (Optional) ────────────────────────────────────
  logging?: {
    level:      'error' | 'warn' | 'info' | 'debug';
    toFile?:    boolean;
    filePath?:  string;
  };

  // ─── Dashboard (Optional) ──────────────────────────────────
  dashboard?: {
    enabled:   boolean;
    port?:     number;
    username?: string;
    password?: string;
  };
});

Per-Monitor Options

uptimeTelegram.monitor(url: string, {
  check?:              string | number;  // '10s' | '1m' | 30000ms
  call?:               boolean;          // Enable voice alert
  sms?:                boolean;          // Enable SMS fallback
  timeout?:            number;           // Request timeout ms (default: 10000)
  failureThreshold?:   number;           // Failures before alert (default: 2)
  recoveryThreshold?:  number;           // Successes before recovery (default: 1)
  expectedStatus?:     number[];         // Valid HTTP codes (default: [200..302])
  expectedContent?:    string;           // String that must exist in response body
  followRedirects?:    boolean;          // Follow redirects (default: true)
  headers?:            Record<string, string>;  // Custom request headers
  auth?: {
    username: string;
    password: string;
  };
});

API Reference

uptimeTelegram.configure(config) → this

Set global configuration. Call once before any monitor() calls.

uptimeTelegram.monitor(url, options?) → Monitor

Start monitoring a URL. Returns a Monitor instance.

uptimeTelegram.stop(url) → this

Stop monitoring a specific URL.

uptimeTelegram.stopAll() → this

Stop all active monitors.

uptimeTelegram.status() → Record<string, MonitorStatus>

Get current status of all monitors.

Monitor Events

'started'   — Monitor started
'stopped'   — Monitor stopped
'check'     — Check completed (fires every interval)
'down'      — Site went down
'up'        — Site recovered
'incident'  — New incident recorded

Architecture Overview

uptime-telegram/
│
├── src/
│   ├── index.ts              ← Public API (Singleton + exports)
│   │
│   ├── core/
│   │   ├── monitor.ts        ← Per-site monitor (EventEmitter)
│   │   ├── checker.ts        ← HTTP check engine
│   │   ├── scheduler.ts      ← Smart interval scheduler
│   │   └── state-manager.ts  ← State machine (up/down/recovering)
│   │
│   ├── notifiers/
│   │   ├── telegram-bot.ts   ← Telegram message notifier
│   │   ├── telegram-call.ts  ← Voice alert via TTS + Telegram
│   │   ├── sms-notifier.ts   ← SMS via Twilio
│   │   └── notifier-factory.ts
│   │
│   ├── config/
│   │   ├── defaults.ts
│   │   ├── validator.ts      ← Joi schema validation
│   │   └── schema.ts
│   │
│   ├── storage/
│   │   ├── memory-store.ts
│   │   ├── file-store.ts
│   │   └── redis-store.ts
│   │
│   ├── dashboard/
│   │   ├── server.ts         ← Express dashboard server
│   │   └── routes.ts
│   │
│   ├── utils/
│   │   ├── logger.ts
│   │   ├── retry.ts
│   │   ├── http-client.ts
│   │   ├── dns-resolver.ts
│   │   └── latency-tracker.ts
│   │
│   └── types/
│       └── index.ts          ← All TypeScript interfaces
│
├── cli/
│   ├── index.ts
│   └── commands/
│       ├── start.ts
│       ├── status.ts
│       ├── add.ts
│       └── remove.ts
│
└── test/ | examples/ | docs/

FAQ

Q: Does it work with private Telegram groups/channels?
A: Yes. Add the bot to your group/channel and use the group's Chat ID.

Q: What's the minimum check interval?
A: 10 seconds on Pro, 60 seconds on Free.

Q: Can I monitor multiple sites?
A: Yes — call uptimeTelegram.monitor() multiple times with different URLs.

Q: Is it production-safe?
A: Yes. Built with TypeScript, full test coverage, retry logic, and zero sensitive data stored.

Q: What Node.js version is required?
A: Node.js ≥ 18.0.0

Contributing

See CONTRIBUTING.md. PRs are welcome!

License

MIT © TIMSoftDZ uptime-telegram contributors