nestjs-telegram-decorators

NestJS module for Telegram Bot API integration through decorators, without telegraf, node-telegram-bot-api, or any other Telegram SDK.

The package talks directly to the official Telegram Bot API over HTTP: https://api.telegram.org.

Features

• TelegramModule.forRoot() and forRootAsync()
• Long polling via getUpdates
• Webhook mode with secret token validation
• Method decorators for routing Telegram updates
• Parameter decorators for extracting the Telegram user and raw update
• Strong TypeScript interfaces for Telegram Bot API payloads
• Nest DI integration
• Guard and interceptor support in Telegram handlers
• Extensible event matcher architecture

Installation

npm install nestjs-telegram-decorators

Peer dependencies:

npm install @nestjs/common @nestjs/core @nestjs/platform-express reflect-metadata rxjs

Quick Start

import { Module } from '@nestjs/common';
import { TelegramModule } from 'nestjs-telegram-decorators';

import { BotUpdates } from './bot-updates';

@Module({
  imports: [
    TelegramModule.forRoot({
      token: process.env.TELEGRAM_BOT_TOKEN!,
    }),
  ],
  providers: [BotUpdates],
})
export class AppModule {}

Handler Example

import { Injectable } from '@nestjs/common';
import {
  Command,
  Message,
  Callback,
  TelegramService,
  TelegramUpdateParam,
  TelegramUserParam,
  type TelegramUpdate,
  type TelegramUser,
} from 'nestjs-telegram-decorators';

@Injectable()
export class BotUpdates {
  constructor(private readonly telegram: TelegramService) {}

  @Command('/start')
  async onStart(
    @TelegramUpdateParam() update: TelegramUpdate,
    @TelegramUserParam() user: TelegramUser | null,
  ) {
    const chatId = update.message?.chat.id;
    if (!chatId) {
      return;
    }

    await this.telegram.sendMessage({
      chat_id: chatId,
      text: `Hello, ${user?.first_name ?? 'guest'}!`,
    });
  }

  @Message(/hello/i)
  async onHello(@TelegramUpdateParam() update: TelegramUpdate) {
    const chatId = update.message?.chat.id;
    if (!chatId) {
      return;
    }

    await this.telegram.sendMessage({
      chat_id: chatId,
      text: 'Hello from NestJS',
    });
  }

  @Callback(/^confirm:/)
  async onConfirm(@TelegramUpdateParam() update: TelegramUpdate) {
    const query = update.callback_query;
    if (!query) {
      return;
    }

    await this.telegram.answerCallbackQuery({
      callback_query_id: query.id,
      text: 'Confirmed',
    });
  }
}

Available Decorators

Method decorators:

• @Command(pattern?: string | RegExp)
• @Message(pattern?: string | RegExp)
• @Callback(pattern?: string | RegExp)
• @EditMessage()
• @Photo()
• @Video()

Parameter decorators:

• @TelegramUserParam() returns TelegramUser | null
• @TelegramUpdateParam() returns the raw TelegramUpdate

Note: the decorators are exported with Param suffixes because the package also exports Telegram API interfaces named TelegramUser and TelegramUpdate.

Polling Mode

Polling is the default mode.

TelegramModule.forRoot({
  token: process.env.TELEGRAM_BOT_TOKEN!,
  mode: 'polling',
  polling: {
    interval: 1000,
    limit: 100,
    timeout: 30,
  },
});

Webhook Mode

TelegramModule.forRoot({
  token: process.env.TELEGRAM_BOT_TOKEN!,
  mode: 'webhook',
  webhook: {
    url: 'https://example.com',
    path: '/telegram/webhook',
    secretToken: 'super-secret-token',
  },
});

In webhook mode the module:

• registers an HTTP POST endpoint in the Nest app
• validates x-telegram-bot-api-secret-token when configured
• calls setWebhook() automatically on startup

TelegramService API

telegram.call(method, payload)
telegram.sendMessage(payload)
telegram.editMessageText(payload)
telegram.answerCallbackQuery(payload)
telegram.sendPhoto(payload)
telegram.sendVideo(payload)

Extensibility

Custom event types can be added through custom TelegramEventMatcher implementations and passed into TelegramModule.forRoot(..., { eventMatchers }) or forRootAsync().

Exported Public API

Root export:

import {
  TelegramModule,
  TelegramService,
  Command,
  Message,
  Callback,
  EditMessage,
  Photo,
  Video,
  TelegramUserParam,
  TelegramUpdateParam,
  type TelegramUpdate,
  type TelegramUser,
} from 'nestjs-telegram-decorators';

Development

npm run build
npm test