outbound only · no inbound ports
v1.1.0
Outbound-only architecture

Notifygram Reliable Telegram Alerting for Node.js

Lightweight Node.js library for app notifications in Telegram. High-priority delivery for mission-critical production alerts, with automatic retry and local queueing.

Install via NPM Read Docs
Performance

The Technical Edge

Built for production reliability. No fluff, just the features you need to stay alerted.

Smart Queue

Strict 1 msg/sec rate limit. Error spikes never get your bot banned by Telegram.

Intelligent Deduplication

Identical errors collapse into one alert — sent after 60s or 2s of silence. No notification fatigue.

Zero Dependencies

Zero NPM packages. Native Node.js only — installs instantly, audits in seconds.

TypeScript Ready

Full typings for options, methods, and log levels — no extra setup, no @types package.

Outbound Only

No webhooks. No long-polling. Unlike Telegraf or grammY — just send and go.

Built-in Notifications

info / warning / error / fatal with icons, auto-metadata, and HTML/Markdown custom() — ready out of the box.

Simplicity

Ease of use

Notifygram is designed to be easy to use. It has a simple and intuitive interface that makes it easy to send notifications to your Telegram channel.

index.js — notifygram-demo
index.js
1
import { createNotifygram } from "notifygram";
2
3
const notifygram = createNotifygram({
4
token: "YOUR_BOT_TOKEN",
5
chatId: "YOUR_CHAT_ID",
6
});
7
8
await notifygram.info("Notifygram is ready");
9
await notifygram.message("First message");
⎇ main ⊘ 0 ⚠ 0
Ln 8, Col 46 UTF-8 JavaScript
17:29
LO
Logger Channel 3 subscribers
Broadcast
In Telegram

Three messages you will actually send

A crash, a new order, a finished script. Same two-line API. Different job in your pocket.

error()

The stack lands in your pocket

One call. Telegram already shows ERROR, service, timestamp, and the stack. No dashboard.

ERROR

Service: Online store

Timestamp: 21.08.2026, 00:28:23 GMT+7

Payment error

Error: Payment error
    at chargeOrder 
      (/app/src/payment.js:42:11)
    at Checkout.pay
      (/app/src/checkout.js:88:7)
1
await notifygram.error(new Error('Payment error'));

custom()

Not a logger. A channel.

HTML table, label Order — a new checkout in Telegram. The message people actually remember.

Order

You have a new order

Order details

Item Quantity Total cost
Item 1 2 100 USD
Item 2 1 50 USD
1
await notifygram.custom(
2
`
3
<h2>You have a new order.</h2>
4
<details>
5
<summary>Order details</summary>
6
<table bordered striped>
7
<tr><th>Item</th><th>Quantity</th><th>Total cost</th></tr>
8
<tr><td>Item 1</td><td>2</td><td>100 USD</td></tr>
9
<tr><td>Item 2</td><td>1</td><td>50 USD</td></tr>
10
</table>
11
</details>
12
`,
13
{ mode: "html", label: "Order" },
14
);

flush()

The process waits for the alert

Cron, CI, serverless: Node can exit before the HTTP call finishes. flush() drains the queue first.

1
await notifygram.flush();

In production set minLevel to "error". Info and warning stay silent.

Integrate

Quick Start

Requires Node.js 18+. From a Telegram bot to a working setup in under a minute.

  1. Create a Telegram bot

    Open @BotFather, create a bot, and copy the API token. Then add the bot to the chat, channel, or group where alerts should arrive. For channels and groups, make the bot an admin.

  2. Install the package

    $ npm install notifygram

  3. Get the chat ID

    Notifygram needs a bot token and a chat ID. Telegram does not show the ID in the app — the CLI finds it for you.

    $ npx notifygram init

    Follow the prompts in the terminal.

    Already have a chat ID? Skip this step and set TELEGRAM_BOT_TOKEN and TELEGRAM_CHAT_ID — see the docs.

  4. Ready to send

    That's it — Notifygram is ready to use. See how sending looks in Ease of use, what arrives in In Telegram, or read the full docs on GitHub.