Annotation Interface CallbackHandler

@Retention(RUNTIME) @Target(METHOD) public @interface CallbackHandler
Annotation for handling incoming callback queries in a declarative manner. Provides a convenient alternative to programmatic callback registration using BotClient.onCallback(FilterExecutor, UpdateHandler).

Basic usage example: 


 @CallbackHandler(data = "hello")
 void handleHelloCallback(BotContext context, CallbackQuery query) {
     // Handle callback with data "hello"
 }
Equivalent to: 

 bot.onCallback(filter -> filter.callbackData("hello"), (ctx, query) -> {});

Advanced example with multiple filters: 


 @CallbackHandler(
     data = {"hi", "hello"},
     chatType = ChatType.PRIVATE,
     state = "awaiting_response"
 )
 void handlePrivateStartCallback(BotContext context, CallbackQuery query) {
     // Handle private chat callbacks with data "hi" or "hello"
     // and only when conversation state is "awaiting_response"
 }
Equivalent to: 

 bot.onCallback(filter ->
     (filter.callbackData("hi") || filter.callbackData("hello")) &&
     filter.Private() &&
     filter.state("awaiting_response"),
     (ctx, query) -> {}
 );

Custom filter example: 


 @CallbackHandler(filter = MyCustomFilter.class)
 void handleCustomCallback(BotContext context, CallbackQuery query) {
     // Handle callback using custom filtering logic
 }
Since:
1.2.0
See Also:

  • Optional Element Summary

    Optional Elements
    Modifier and Type
    Optional Element
    Description
    ChatType[]
    chatType
    Specifies the chat types where this callback handler should be active.
    String[]
    data
    Specifies the callback data values to match.
    Class<? extends CustomFilter>
    filter
    Custom filter class for advanced filtering logic beyond the built-in options.
    int
    priority
    Priority order for handler registration and execution.
    String
    regex
    Regular expression pattern to match against callback data.
    String
    state
    Conversation state required for this callback handler to trigger.

  • Element Details

    • data

      String[] data
      Specifies the callback data values to match. Multiple values are combined using OR logic - the handler will trigger if the callback data matches any of the specified values.
      Returns:
      array of callback data strings to match
      Default:
      {}

    • chatType

      ChatType[] chatType
      Specifies the chat types where this callback handler should be active. Multiple chat types are combined using OR logic - the handler will trigger if the chat type matches any of the specified types.
      Returns:
      array of ChatType enum values to filter by
      Default:
      {}

    • regex

      String regex
      Regular expression pattern to match against callback data. The handler will trigger if the callback data matches the specified regex pattern.
      Returns:
      regex pattern string for callback data matching
      Default:
      ""

    • filter

      Class<? extends CustomFilter> filter
      Custom filter class for advanced filtering logic beyond the built-in options. Use this when you need complex or application-specific filtering conditions that cannot be expressed through the other annotation parameters.
      Returns:
      class implementing CustomFilter interface
      Default:
      io.github.natanimn.telebof.filters.DefaultCustomFilter.class

    • state

      String state
      Conversation state required for this callback handler to trigger. The handler will only be invoked if the current conversation state matches the specified state value.
      Returns:
      required conversation state string
      Default:
      ""

    • priority

      int priority
      Priority order for handler registration and execution. Handlers with lower priority numbers are registered and executed before those with higher numbers. This allows controlling the order of handler processing when multiple handlers could match the same callback.
      Returns:
      priority integer value (lower = earlier execution)
      Default:
      0