Nestgram v2.0
Docs/Routing

Update types

Telegram delivers one Update object per event, and exactly one of its fields is populated — message, callback_query, chat_member, and so on. Each of those field names is an update kind, and each kind has an @On* decorator that binds a handler to it. The handler’s first parameter is the concrete typed event for that kind, positional, no decorator:

membership.router.ts
import { Router, OnChatMember, ChatMemberUpdated } from 'nestgram';

@Router()
export class MembershipRouter {
  @OnChatMember()
  membershipChanged(update: ChatMemberUpdated) {
    return `${update.new_chat_member.user.first_name} is now ${update.new_chat_member.status}`;
  }
}

How a kind reaches your handler

The @On* decorator records one thing on the method: the raw update-field name it listens to ('chat_member'). At boot, DiscoveryService collects every such binding into the route table, bucketed by that field name. Nothing reflects per update.

Per update, resolveKind reads which field the Update carries and returns the matching UpdateKind; the route matcher then pulls only the bucket for that kind and runs its predicates in declaration order, first match wins. So the @On* field name and the resolved kind are the same string on both sides of the table — that’s the whole binding.

Mental model
update field→resolveKind→route table bucket→predicates→first match

resolveKind walks an explicit whitelist — the UpdateKind enum — and returns null for any field not in it. It never guesses from the shape of the payload. That’s the second invariant worth knowing:

The @On* catalog

Every kind in the UpdateKind whitelist has an @On* decorator. The first parameter is the event class in the Event column.

DecoratorEventUpdate field
@OnMessage()Messagemessage
@OnEditedMessage()Messageedited_message
@OnChannelPost()Messagechannel_post
@OnEditedChannelPost()Messageedited_channel_post
@OnBusinessConnection()BusinessConnectionbusiness_connection
@OnBusinessMessage()Messagebusiness_message
@OnEditedBusinessMessage()Messageedited_business_message
@OnDeletedBusinessMessage()BusinessMessagesDeleteddeleted_business_messages
@OnGuestMessage()Messageguest_message
@OnMessageReaction()MessageReactionUpdatedmessage_reaction
@OnMessageReactionCount()MessageReactionCountUpdatedmessage_reaction_count
@OnInlineQuery()InlineQueryinline_query
@OnChosenInlineResult()ChosenInlineResultchosen_inline_result
@OnCallbackQuery()CallbackQuerycallback_query
@OnShippingQuery()ShippingQueryshipping_query
@OnPreCheckoutQuery()PreCheckoutQuerypre_checkout_query
@OnPurchasedPaidMedia()PaidMediaPurchasedpurchased_paid_media
@OnPoll()Pollpoll
@OnPollAnswer()PollAnswerpoll_answer
@OnMyChatMember()ChatMemberUpdatedmy_chat_member
@OnChatMember()ChatMemberUpdatedchat_member
@OnChatJoinRequest()ChatJoinRequestchat_join_request
@OnChatBoost()ChatBoostUpdatedchat_boost
@OnRemovedChatBoost()ChatBoostRemovedremoved_chat_boost
@OnSubscription()BotSubscriptionUpdatedsubscription
@OnManagedBot()ManagedBotUpdatedmanaged_bot
@OnMessageGenerationStopped()MessageGenerationStoppedstopped_message_generation

Every @On* takes optional predicates as arguments — extra match conditions, all of which must pass — but that’s narrowing within one kind, covered on the routing page. This page is about the kind binding itself.

Several kinds, one handler

You usually write one handler per kind and call a shared private method. When a single method genuinely fits several kinds, stack the decorators — each one records its own kind binding on the method, so the method lands in every matching bucket. The parameter becomes a union of the event classes, and you narrow it with instanceof (events are real classes, not interfaces).

feedback.router.ts
import {
  Router,
  OnMessage,
  OnCallbackQuery,
  Message,
  CallbackQuery,
} from 'nestgram';

@Router()
export class FeedbackRouter {
  @OnMessage()
  @OnCallbackQuery()
  handle(event: Message | CallbackQuery) {
    if (event instanceof Message) {
      return event.answer(`You said: ${event.text}`);
    }
    return event.answer('Got it');
  }
}
1

Stacking @OnMessage() and @OnCallbackQuery() records two kind bindings on the one method — no union decorator needed; each binding routes its own kind.

2

The parameter is a union of the matching event classes — no hidden optionals, no god-context.

3

instanceof Message narrows the union, so you reach a kind-specific field only after a deliberate check — plain TypeScript, nothing framework-specific.

What Telegram actually sends

A handler only fires if Telegram delivers its kind — and a few kinds are held back unless requested by name: chat_member, message_reaction, and message_reaction_count. With most libraries an @OnChatMember() handler compiles, deploys, and then never fires, with no error anywhere.

Nestgram closes that gap at boot: it derives allowed_updates from your handlers — every kind some @On* binds to is requested, for getUpdates in polling mode and in the setWebhook registration in webhook mode. Write @OnChatMember() and chat_member updates arrive; nothing to configure.

To take manual control, pass an explicit list — it wins over the derived one:

app.module.ts
import { NestgramModule } from 'nestgram';

NestgramModule.forRoot({
  token: process.env.BOT_TOKEN ?? '',
  polling: { allowed_updates: ['message', 'callback_query'] },
});

The list values are the same update-field strings, typed as AllowedUpdate (the string values of UpdateKind), so you write plain literals with autocomplete and no enum import. With an explicit list, any handler bound to a kind the list omits is dead code — Telegram never delivers it. Nestgram warns about each such handler at boot, naming the router and method, so the mistake is one log line instead of a production mystery.