Annotation Interface MessageHandler

@Retention(RUNTIME) @Target(METHOD) @Repeatable(MessageHandlers.class) public @interface MessageHandler
Annotation for handling incoming messages in a declarative manner. Provides a convenient alternative to programmatic message registration using BotClient.onMessage(FilterExecutor, UpdateHandler).

Basic command handler example: 


 @MessageHandler(commands = "start")
 void handleStartCommand(BotContext context, Message message) {
     // Handle /start command
 }
Equivalent to: 

 bot.onMessage(filter -> filter.commands("start"), (ctx, message) -> {});

Advanced example with multiple filters: 


 @MessageHandler(
     commands = {"help", "support"},
     chatType = ChatType.PRIVATE,
     state = "awaiting_help"
 )
 void handlePrivateHelp(BotContext context, Message message) {
     // Handle private text messages with commands /help or /support
     // matching specific conversation state
 }
Equivalent to: 

 bot.onMessage(filter ->
     (filter.commands("help") || filter.commands("support")) &&
     filter.Private() &&
     filter.state("awaiting_help"),
     (ctx, message) -> {}
 );

Media message example: 


 @MessageHandler(type = {MessageType.PHOTO, MessageType.VIDEO})
 void handleMediaMessages(BotContext context, Message message) {
     // Handle both photo and video messages
 }
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 message handler should be active.
    String[]
    commands
    Specifies the bot commands to match (e.g., "/start", "/help").
    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 message text content.
    String
    state
    Conversation state required for this message handler to trigger.
    String[]
    texts
    Specifies exact text content to match in the message.
    MessageType[]
    type
    Specifies the message types to match (text, photo, video, etc.).

  • Element Details

    • commands

      String[] commands
      Specifies the bot commands to match (e.g., "/start", "/help"). Multiple commands are combined using OR logic - the handler will trigger if the message contains any of the specified commands.
      Returns:
      array of command strings to match
      Default:
      {}

    • texts

      String[] texts
      Specifies exact text content to match in the message. Multiple texts are combined using OR logic - the handler will trigger if the message text exactly matches any of the specified strings.
      Returns:
      array of exact text strings to match
      Default:
      {}

    • chatType

      ChatType[] chatType
      Specifies the chat types where this message 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 message text content. The handler will trigger if the message text matches the specified regex pattern.
      Returns:
      regex pattern string for message text matching
      Default:
      ""

    • type

      MessageType[] type
      Specifies the message types to match (text, photo, video, etc.). Multiple message types are combined using OR logic - the handler will trigger if the message type matches any of the specified types.
      Returns:
      array of MessageType enum values to filter by
      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 message 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 message.
      Returns:
      priority integer value (lower = earlier execution)
      Default:
      0