-
Notifications
You must be signed in to change notification settings - Fork 4
Annotation overview
Tim4ik edited this page Aug 3, 2025
·
3 revisions
This document provides a comprehensive overview of all filter attributes available in the Telegrator framework. These attributes are used to declaratively specify when handlers should be executed based on various conditions.
- Message Filters
- Command Filters
- Callback Query Filters
- Environment Filters
- State Management Filters
- Utility Filters
Filters messages that contain a specific substring.
[MessageHandler]
[TextContains("hello")]
public class HelloHandler : MessageHandler
{
// Handles messages containing "hello"
}
// Case-insensitive matching
[TextContains("hello", StringComparison.InvariantCultureIgnoreCase)]Parameters:
-
content(string): The substring to search for -
comparison(StringComparison, optional): String comparison method (default:InvariantCulture)
Filters messages that start with a specific string.
[MessageHandler]
[TextStartsWith("/")]
public class CommandHandler : MessageHandler
{
// Handles messages starting with "/"
}Parameters:
-
content(string): The prefix to match -
comparison(StringComparison, optional): String comparison method
Filters messages that end with a specific string.
[MessageHandler]
[TextEndsWith("!")]
public class ExclamationHandler : MessageHandler
{
// Handles messages ending with "!"
}Parameters:
-
content(string): The suffix to match -
comparison(StringComparison, optional): String comparison method
Filters messages that exactly match a specific string.
[MessageHandler]
[TextEquals("ping")]
public class PingHandler : MessageHandler
{
// Handles messages that exactly equal "ping"
}Parameters:
-
content(string): The exact text to match -
comparison(StringComparison, optional): String comparison method
Filters messages that contain any non-empty text.
[MessageHandler]
[HasText]
public class TextHandler : MessageHandler
{
// Handles any message with text content
}Parameters: None
Filters messages using regular expressions.
[MessageHandler]
[MessageRegex(@"^\d+$")]
public class NumberHandler : MessageHandler
{
// Handles messages containing only digits
}
// With regex options
[MessageRegex(@"hello\s+world", RegexOptions.IgnoreCase)]Parameters:
-
pattern(string): Regular expression pattern -
regexOptions(RegexOptions, optional): Regex options -
regex(Regex): Precompiled regex object
Filters messages from a specific user ID.
[MessageHandler]
[FromUserId(123456789)]
public class AdminHandler : MessageHandler
{
// Handles messages from user with ID 123456789
}Parameters:
-
userId(long): The user ID to match
Filters messages from a specific username.
[MessageHandler]
[FromUsername("john_doe")]
public class JohnHandler : MessageHandler
{
// Handles messages from user with username "john_doe"
}
// Case-insensitive matching
[FromUsername("john_doe", StringComparison.InvariantCultureIgnoreCase)]Parameters:
-
username(string): The username to match -
comparison(StringComparison, optional): String comparison method
Filters messages from a user with specific name.
[MessageHandler]
[FromUser("John")]
public class JohnHandler : MessageHandler
{
// Handles messages from user with first name "John"
}
[FromUser("John", "Doe")]
public class JohnDoeHandler : MessageHandler
{
// Handles messages from user with first name "John" and last name "Doe"
}Parameters:
-
firstName(string): The first name to match -
lastName(string, optional): The last name to match -
comparison(StringComparison, optional): String comparison method
Filters messages sent by bots.
[MessageHandler]
[FromBot]
public class BotMessageHandler : MessageHandler
{
// Handles messages sent by bots
}Parameters: None
Filters messages sent by users (not bots).
[MessageHandler]
[NotFromBot]
public class UserMessageHandler : MessageHandler
{
// Handles messages sent by users (not bots)
}Parameters: None
Filters messages from premium users.
[MessageHandler]
[FromPremiumUser]
public class PremiumHandler : MessageHandler
{
// Handles messages from premium users
}Parameters: None
Filters messages from specific chat types.
[MessageHandler]
[ChatType(ChatType.Private)]
public class PrivateChatHandler : MessageHandler
{
// Handles messages from private chats
}
[MessageHandler]
[ChatType(ChatType.Group)]
public class GroupChatHandler : MessageHandler
{
// Handles messages from group chats
}
// Using flags for multiple types
[ChatType(ChatTypeFlags.Private | ChatTypeFlags.Group)]Parameters:
-
type(ChatType): The chat type to match -
flags(ChatTypeFlags): Multiple chat types using flags
Filters messages from a specific chat.
[MessageHandler]
[ChatId(-1001234567890)]
public class SpecificChatHandler : MessageHandler
{
// Handles messages from specific chat
}Parameters:
-
id(long): The chat ID to match
Filters messages from chats with specific title.
[MessageHandler]
[ChatTitle("My Group")]
public class MyGroupHandler : MessageHandler
{
// Handles messages from chat with title "My Group"
}Parameters:
-
title(string): The chat title to match -
comparison(StringComparison, optional): String comparison method
Filters messages from chats with specific username.
[MessageHandler]
[ChatUsername("mygroup")]
public class MyGroupHandler : MessageHandler
{
// Handles messages from chat with username "mygroup"
}Parameters:
-
userName(string): The chat username to match -
comparison(StringComparison, optional): String comparison method
Filters messages from chats with specific name.
[MessageHandler]
[ChatName("My", "Group")]
public class MyGroupHandler : MessageHandler
{
// Handles messages from chat with first name "My" and last name "Group"
}Parameters:
-
firstName(string): The chat first name to match -
lastName(string, optional): The chat last name to match -
comparison(StringComparison, optional): String comparison method
Filters messages from forum chats.
[MessageHandler]
[ChatIsForum]
public class ForumHandler : MessageHandler
{
// Handles messages from forum chats
}Parameters: None
Filters messages that are replies to messages sent by this bot.
[MessageHandler]
[MeReplied]
public class ReplyToBotHandler : MessageHandler
{
// Handles messages that reply to bot's messages
}Parameters: None
Filters messages that have replies.
[MessageHandler]
[HasReply]
public class RepliedMessageHandler : MessageHandler
{
// Handles messages that have replies
}
// Check for specific reply depth
[HasReply(2)]
public class DeepReplyHandler : MessageHandler
{
// Handles messages with reply depth of 2
}Parameters:
-
replyDepth(int, optional): The reply depth to check (default: 1)
Filters messages based on reply chain content.
[MessageHandler]
[FromReplyChain]
public class ReplyChainHandler : MessageHandler
{
// Handles messages from reply chains
}Parameters:
-
replyDepth(int, optional): The reply depth to check (default: 1)
Filters messages with specific entities (mentions, links, etc.).
[MessageHandler]
[MessageHasEntity(MessageEntityType.Mention)]
public class MentionHandler : MessageHandler
{
// Handles messages with mentions
}
[MessageHandler]
[MessageHasEntity(MessageEntityType.Url)]
public class LinkHandler : MessageHandler
{
// Handles messages with URLs
}
// With specific content
[MessageHasEntity(MessageEntityType.Mention, "@mybot")]
public class BotMentionHandler : MessageHandler
{
// Handles messages mentioning "@mybot"
}Parameters:
-
type(MessageEntityType): The entity type to match -
offset(int, optional): Starting position of the entity -
length(int?, optional): Length of the entity -
content(string, optional): Content that the entity should contain -
stringComparison(StringComparison, optional): String comparison method
Filters messages with dice throws.
[MessageHandler]
[DiceThrowed(6)]
public class DiceSixHandler : MessageHandler
{
// Handles dice throws with value 6
}
[MessageHandler]
[DiceThrowed(DiceType.Dart, 1)]
public class DartHandler : MessageHandler
{
// Handles dart throws with value 1
}Parameters:
-
value(int): The dice value to match -
diceType(DiceType, optional): The type of dice
Filters automatically forwarded messages.
[MessageHandler]
[IsAutomaticFormwardMessage]
public class ForwardHandler : MessageHandler
{
// Handles automatically forwarded messages
}Parameters: None
Filters messages sent while the user was offline.
[MessageHandler]
[IsFromOfflineMessage]
public class OfflineMessageHandler : MessageHandler
{
// Handles messages sent while user was offline
}Parameters: None
Filters service messages (user joined, left, etc.).
[MessageHandler]
[IsServiceMessageMessage]
public class ServiceMessageHandler : MessageHandler
{
// Handles service messages
}Parameters: None
Filters topic messages in forum chats.
[MessageHandler]
[IsTopicMessageMessage]
public class TopicMessageHandler : MessageHandler
{
// Handles topic messages in forum chats
}Parameters: None
Filters messages based on command aliases.
[CommandHandler]
[CommandAllias("start")]
public class StartHandler : CommandHandler
{
// Handles /start command
}
[CommandHandler]
[CommandAllias("help", "h")]
public class HelpHandler : CommandHandler
{
// Handles both /help and /h commands
}
// With description
[CommandAllias("settings")]
public class SettingsHandler : CommandHandler
{
public SettingsHandler()
{
Description = "Configure bot settings";
}
}Parameters:
-
alliases(params string[]): Command aliases to match -
Description(property): Command description for Telegram
Filters callback queries with specific data.
[CallbackQueryHandler]
[CallbackData("button1")]
public class Button1Handler : CallbackQueryHandler
{
// Handles callback queries with data "button1"
}Parameters:
-
data(string): The callback data to match
Filters callback queries from specific inline messages.
[CallbackQueryHandler]
[CallbackInlineId("inline_message_id")]
public class InlineHandler : CallbackQueryHandler
{
// Handles callback queries from specific inline message
}Parameters:
-
inlineMessageId(string): The inline message ID to match
Filters updates that occur in debug environment.
[MessageHandler]
[IsDebugEnvironment]
public class DebugHandler : MessageHandler
{
// Only runs in debug mode
}Parameters: None
Filters updates that occur in release environment.
[MessageHandler]
[IsReleaseEnvironment]
public class ReleaseHandler : MessageHandler
{
// Only runs in release mode
}Parameters: None
Filters updates based on environment variable values.
[MessageHandler]
[EnvironmentVariable("BOT_MODE", "production")]
public class ProductionHandler : MessageHandler
{
// Only runs when BOT_MODE=production
}
[MessageHandler]
[EnvironmentVariable("ENABLE_FEATURE")]
public class FeatureHandler : MessageHandler
{
// Only runs when ENABLE_FEATURE environment variable exists
}Parameters:
-
variable(string): The environment variable name -
value(string, optional): The expected value -
comparison(StringComparison, optional): String comparison method
Filters handlers based on numeric (integer) state.
[MessageHandler]
[NumericState(1)]
public class Step1Handler : MessageHandler
{
// Handles messages when user is in state 1
}
[MessageHandler]
[NumericState(SpecialState.NoState)]
public class StartHandler : MessageHandler
{
// Handles messages when user has no state
}Parameters:
-
myState(int): The numeric state to match -
specialState(SpecialState): Special state value -
keyResolver(IStateKeyResolver, optional): Custom key resolver
Filters handlers based on enum state.
public enum UserState
{
Start = SpecialState.NoState,
WaitingForName,
WaitingForAge
}
[MessageHandler]
[EnumState<UserState>(UserState.WaitingForName)]
public class NameHandler : MessageHandler
{
// Handles messages when user is in WaitingForName state
}Parameters:
-
myState(TEnum): The enum state to match -
specialState(SpecialState): Special state value -
keyResolver(IStateKeyResolver, optional): Custom key resolver
Filters handlers based on string state.
[MessageHandler]
[StringState("waiting_for_name")]
public class NameHandler : MessageHandler
{
// Handles messages when user is in "waiting_for_name" state
}Parameters:
-
myState(string): The string state to match -
specialState(SpecialState): Special state value -
keyResolver(IStateKeyResolver, optional): Custom key resolver
public enum SpecialState
{
None, // No special state
NoState, // Indicates that no state is present
AnyState // Indicates that any state is acceptable
}Filters messages that contain mentions.
[MessageHandler]
[Mentioned]
public class MentionHandler : MessageHandler
{
// Handles any message with mentions of this bot
}
[MessageHandler]
[Mentioned("rikitav")]
public class BotMentionHandler : MessageHandler
{
// Handles messages mentioning "@rikitav"
}
[MessageHandler]
[Mentioned("rikitav", 0)]
public class BotMentionAtStartHandler : MessageHandler
{
// Handles messages mentioning "@rikitav" in the start of the message
}Parameters:
-
mention(string, optional): Specific mention text to match -
offset(int, optional): Position where mention should occur
Filters /start commands in private chats.
[MessageHandler]
[Welcome]
public class WelcomeHandler : MessageHandler
{
// Handles /start command in private chats
}
[MessageHandler]
[Welcome(true)]
public class FirstTimeWelcomeHandler : MessageHandler
{
// Handles only first-time /start commands (message ID = 0)
}Parameters:
-
onlyFirst(bool, optional): Only handle first-time start commands (default: false)
Filters can be combined using logical operators:
[MessageHandler]
[ChatType(ChatType.Private)]
[TextContains("hello")]
public class PrivateHelloHandler : MessageHandler
{
// Handles "hello" messages in private chats (AND logic)
}
[MessageHandler]
[TextContains("hello", Modifiers = FilterModifier.OrNext)]
[TextContains("hi")]
public class GreetingHandler : MessageHandler
{
// Handles messages containing "hello" OR "hi" (OR logic)
}
[MessageHandler]
[TextContains("hello", Modifiers = FilterModifier.Not)]
public class NotHelloHandler : MessageHandler
{
// Handles messages that do NOT contain "hello" (NOT logic)
}-
FilterModifier.Not- Inverts the filter -
FilterModifier.OrNext- Combines this filter with the next one using OR logic - These can be combined using bitwise OR:
FilterModifier.Not | FilterModifier.OrNext
- Use specific filters: Prefer specific filters over generic ones for better performance
- Combine filters logically: Use multiple filters to create precise conditions
- Order matters: Place more restrictive filters first
- Use state management: For multi-step conversations, use state filters
- Environment awareness: Use environment filters for different deployment scenarios
- Document your filters: Add comments explaining complex filter combinations
[CommandHandler]
[CommandAllias("admin")]
[FromUserId(123456789)]
[IsReleaseEnvironment]
public class AdminHandler : CommandHandler
{
// Only admin can use this command in production
}[MessageHandler]
[EnumState<UserState>(UserState.WaitingForName)]
[HasText]
public class NameInputHandler : MessageHandler
{
// Handles name input in form wizard
}