| 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 { }:
| Handler | Purpose |
|---|
onCommand("/start") { } | Commands (e.g. /start) |
onInput("id") { } | Single-step input; route via bot.inputListener[user] = "id" |
inputChain("id") { }.andThen { } | Multi-step input chain |
common("text") { } or common(Regex("...")) { } | Text/regex match (lower priority than commands) |
onUpdate(UpdateType.X) { } | All updates of given type |
whenNotHandled { } | Fallback for unprocessed updates |
Typed Update Handlers
Use typed wrappers for ActivityCtx<XxxUpdate>:
onMessage { } — MessageUpdateonCallbackQuery { } — CallbackQueryUpdateonInlineQuery { } — InlineQueryUpdateonEditedMessage { }, onChannelPost { }, onChatMember { }, etc.
Input Listener
Route the next user message to an input handler or chain:
bot.inputListener[user] = "conversation"
bot.inputListener.set(user) { "conversation-2step" }
Annotation Handlers
| Annotation | Purpose |
|---|
@CommandHandler(["/start"]) | Command handler |
@CommandHandler.CallbackQuery(["/data"]) | Callback query with optional autoAnswer |
@InputHandler(["id"]) | Input handler |
@CommonHandler.Text(["value"]) or @CommonHandler.Regex("...") | Text/regex match |
@UpdateHandler([UpdateType.MESSAGE, ...]) | Update type handler |
@UnprocessedHandler | Fallback |
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
| Annotation | Parameters | Default |
|---|
@CommandHandler | value (commands), scope (UpdateType[]) | scope: MESSAGE |
@CommandHandler.CallbackQuery | value (callback data prefixes), autoAnswer (bool) | autoAnswer: false |
@InputHandler | value (input identifiers) | — |
@CommonHandler.Text | value, filters, priority, scope | filters: [], priority: 0, scope: MESSAGE |
@CommonHandler.Regex | value (pattern), options, filters, priority, scope | options: [], filters: [], priority: 0, scope: MESSAGE |
@UpdateHandler | type (UpdateType[]) | — |
@UnprocessedHandler | — | — |
@Guard | guard (KClass) | DefaultGuard |
@ArgParser | argParser (KClass) | DefaultArgParser |
@RateLimits | period (ms), rate (requests) | 0, 0 |
Reference
