handle-callback-query

Handle Callback Query

Quick Start

Register a handler and always answer the callback query to stop the loading state:

bot.setFunctionality {
    onCallbackQuery {
        val cq = update.callbackQuery
        answerCallbackQuery(cq.id).options { text = "Done!" }.send(user, bot)
        when (cq.data) {
            "yes" -> message("You said yes!").send(user, bot)
            "no" -> message("You said no.").send(user, bot)
        }
    }
}

Handler Registration

• DSL: onCallbackQuery { } — typed ActivityCtx<CallbackQueryUpdate>
• Annotation: @CommandHandler.CallbackQuery(["prefix"]) with optional autoAnswer = true

Accessing Callback Data

• update.callbackQuery — the CallbackQuery
• callbackQuery.id — required for answerCallbackQuery
• callbackQuery.data — button data (1-64 bytes), may be null
• callbackQuery.from — user who pressed
• callbackQuery.message — message with the button (if any)

Answering the Query

Always call answerCallbackQuery to remove the loading state:

answerCallbackQuery(callbackQuery.id).send(user, bot)

With options:

answerCallbackQuery(callbackQuery.id).options {
    text = "Saved!"           // Notification text (0-200 chars)
    showAlert = true         // Alert instead of top notification
    url = "https://..."      // URL to open (e.g. t.me/bot?start=xxx)
    cacheTime = 60           // Cache result (seconds)
}.send(user, bot)

Parsing Callback Data

Use prefixes for routing: "action:id", "vote:123":

cq.data?.split(":", limit = 2)?.let { (action, id) ->
    when (action) {
        "vote" -> handleVote(id.toLong())
        "page" -> showPage(id.toInt())
    }
}

@ParamMapping

Maps handler parameters to keys in the parsed parameters map. Use with @CommandHandler.CallbackQuery when the ArgumentParser extracts named values from callback data (e.g. page=1, id=123):

@CommandHandler.CallbackQuery(["vote"], autoAnswer = true)
suspend fun handleVote(
    @ParamMapping("id") itemId: Long,
    user: User,
    bot: TelegramBot
) {
    message("Voted for $itemId").send(user, bot)
}