Telegram

Send notifications through the Telegram Bot API. Return a plain string or a fluent TelegramMessage with a parse mode, routed to a chat id per notifiable.

The Telegram channel sends a notification through the Bot API's sendMessage method. Return a plain string for the message text, or a fluent TelegramMessage when you want to set a parse mode (Markdown or HTML). Delivery uses the platform fetch.

Install

pnpm add @dudousxd/nestjs-notifications-telegram

npm install @dudousxd/nestjs-notifications-telegram

Register the channel

app.module.ts

import { TelegramChannelModule } from '@dudousxd/nestjs-notifications-telegram';

@Module({
  imports: [
    TelegramChannelModule.forRoot({ botToken: process.env.TELEGRAM_BOT_TOKEN }),
  ],
})
export class AppModule {}

TelegramChannelModule.forRoot() takes:

Option	Type	Default	Description
`botToken`	`string`	—	Bot token for the Telegram Bot API. Used to build the request URL.
`global`	`boolean`	`true`	Register globally so the channel is discoverable app-wide.

The notification side

Annotate the payload method with the @Telegram() handle and return a string:

import { type Notifiable, Notification } from '@dudousxd/nestjs-notifications-core';
import { Telegram } from '@dudousxd/nestjs-notifications-telegram';

@Notification()
export class LoginCode {
  constructor(private code: string) {}

  @Telegram()
  toTelegram({ notifiable }: ChannelContext): string {
    return `Your code is ${this.code}`;
  }
}

The Telegram handle also works as a via() token (via() { return [Telegram]; }) for explicit routing; implement TelegramNotification alongside the decorator for compile-time checks on toTelegram().

TelegramMessage builder

Return a TelegramMessage when you need a parse mode for rich formatting. Each method returns this:

deploy-finished.notification.ts

import { Telegram, TelegramMessage } from '@dudousxd/nestjs-notifications-telegram';

@Telegram()
toTelegram({ notifiable }: ChannelContext): TelegramMessage {
  return new TelegramMessage()
    .text('*Deploy finished*')
    .parseMode('MarkdownV2');
}

Method	Effect
`.text(s)`	Set the message text.
`.parseMode(mode)`	Set the `parse_mode` — `'MarkdownV2'`, `'Markdown'`, or `'HTML'`.

Routing the chat

The chat id comes from routeNotificationFor('telegram') — return the chat id to message:

user.ts

export class User implements Notifiable {
  constructor(public telegramChatId: string) {}

  routeNotificationFor(channel: string) {
    if (channel !== 'telegram') return undefined;
    return this.telegramChatId; // a chat id (string or number)
  }
}

The channel needs both a botToken (in forRoot()) and a chat id (from the route). It throws a clear error if either is missing.

Install

Register the channel

The notification side

TelegramMessage builder

Routing the chat

On this page