name: setup-bot-handlers description: [Bot developer] Sets up bot handlers using DSL or annotations. Use when configuring command handlers, input handlers, common handlers, update handlers, or fallback handlers for the telegram-bot library.

Setup Bot Handlers

Two Approaches

• DSL: bot.setFunctionality { ... } — define handlers inline
• Annotations: @CommandHandler, @InputHandler, etc. — KSP generates activities; use with bot.handleUpdates() (loads handlers via META-INF)

DSL Handlers

Inside bot.setFunctionality { }:

Typed Update Handlers

Use typed wrappers for ActivityCtx<XxxUpdate>:

• onMessage { } — MessageUpdate
• onCallbackQuery { } — CallbackQueryUpdate
• onInlineQuery { } — InlineQueryUpdate
• onEditedMessage { }, onChannelPost { }, onChatMember { }, etc.

Input Listener

Route the next user message to an input handler or chain:

bot.inputListener[user] = "conversation"
// or
bot.inputListener.set(user) { "conversation-2step" }

Annotation Handlers

Guards

Add pre-processing checks:

• DSL: guard = UserPresentGuard::class (or DefaultGuard::class)
• Annotation: @Guard(UserPresentGuard::class) or @Guard(guard = UserPresentGuard::class)

Supported by: CommandHandler, CommandHandler.CallbackQuery, InputHandler.

Rate Limits

• DSL: rateLimits = RateLimits.NOT_LIMITED or custom
• Annotation: @RateLimits(period = 60_000, rate = 5) — 5 requests per 60 seconds
• Default: no limit

Supported by: CommandHandler, CallbackQuery, InputHandler, CommonHandler.

ArgParser

Custom argument parsing for commands and callback data:

• Annotation: @ArgParser(argParser = CustomArgParser::class)
• Supported by: CommandHandler, CallbackQuery, CommonHandler
• Default: DefaultArgParser

Annotation Reference

Reference

• CommandHandler.kt
• CommonHandler.kt
• FunctionalHandlingDsl.kt
• FunctionalDSLUtils.kt
• telegram-bot-handling.mdc