Gogram Filters
Filters are used to specify conditions that messages or callbacks must meet before a handler is executed. They help keep your code clean by separating routing logic from your main handler functions.
Important: By default, handlers ignore outgoing messages (sent by yourself/bot). If you want to handle self-sent messages, you must include the telegram.IsOutgoing filter explicitly.
Chat Type Filters
| Filter | Description | Example |
|---|
IsPrivate | Matches private (1-on-1) chats. | telegram.IsPrivate |
IsGroup | Matches group chats. | telegram.IsGroup |
IsChannel | Matches channel chats. | telegram.IsChannel |
Message Type Filters
| Filter | Description | Example |
|---|
IsCommand | Messages starting with a command prefix (default /). | telegram.IsCommand |
IsReply | Messages that are replies to others. | telegram.IsReply |
IsForward | Forwarded messages. | telegram.IsForward |
IsText | Messages with non-empty text. | telegram.IsText |
IsEdited | Messages that have been edited. | telegram.IsEdited |
IsOutgoing | Messages sent by the current user/bot. | telegram.IsOutgoing |
IsIncoming | Messages received from others. | telegram.IsIncoming |
Content Filters
| Filter | Description | Example |
|---|
HasMedia | Messages containing any media. | telegram.HasMedia |
HasPhoto | Messages containing a photo. | telegram.HasPhoto |
HasVideo | Messages containing a video. | telegram.HasVideo |
HasDocument | Messages containing a document/file. | telegram.HasDocument |
HasAudio | Messages containing an audio/music file. | telegram.HasAudio |
HasSticker | Messages containing a sticker. | telegram.HasSticker |
HasAnimation | Messages containing a GIF/animation. | telegram.HasAnimation |
HasVoice | Messages containing a voice note. | telegram.HasVoice |
HasVideoNote | Messages containing a video note. | telegram.HasVideoNote |
HasContact | Messages containing a contact. | telegram.HasContact |
HasLocation | Messages containing a geo location. | telegram.HasLocation |
HasVenue | Messages containing a venue. | telegram.HasVenue |
HasPoll | Messages containing a poll. | telegram.HasPoll |
HasMention | Messages where the current bot is mentioned. | telegram.HasMention |
FromBot | Messages sent by another bot. | telegram.FromBot |
Parameterized Filters
| Filter | Description | Example |
|---|
FromUsers(ids...) | From specific user IDs. | telegram.FromUsers(123456) |
FromChats(ids...) | From specific chat/channel IDs. | telegram.FromChats(-100123...) |
TextMinLen(n) | Text length greater than or equal to n. | telegram.TextMinLen(5) |
TextMaxLen(n) | Text length less than or equal to n. | telegram.TextMaxLen(100) |
Logical Composition
Combine multiple filters using logical operators.
| Operator | Description | Usage |
|---|
Any(filters...) | Matches if any filter matches (OR). | telegram.Any(telegram.HasPhoto, telegram.HasVideo) |
All(filters...) | Matches only if all filters match (AND). | telegram.All(telegram.IsPrivate, telegram.IsCommand) |
Not(filter) | Negates the provided filter (NOT). | telegram.Not(telegram.FromBot) |
Basic Examples
Simple Filtering
Pass filters as additional arguments to client.On. Multiple filters passed this way are treated as an implicit AND.
// Only handle private messages
client.On("message", handler, telegram.IsPrivate)
// Only handle photos in groups
client.On("message", handler, telegram.IsGroup, telegram.HasPhoto)
Logical OR
Use Any to handle multiple media types in a single handler.
// Handle both photos and videos
client.On("message", handler, telegram.Any(telegram.HasPhoto, telegram.HasVideo))
Identity Filtering
Restrict your bot to specific users or chats.
// Only respond to specific users
client.On("message", handler, telegram.FromUsers(123456, 789012))
// Ignore messages from bots
client.On("message", handler, telegram.Not(telegram.FromBot))
Advanced Usage
Custom Filters
You can create your own filters using CustomFilter for messages or CustomCallback for callback queries.
// Custom logic for messages
adminFilter := telegram.CustomFilter(func(m *telegram.NewMessage) bool {
return m.SenderID() == 123456789
})
client.On("message", handler, adminFilter)
// Custom logic for callbacks
callbackFilter := telegram.CustomCallback(func(c *telegram.CallbackQuery) bool {
return strings.HasPrefix(c.DataString(), "admin_")
})
client.On("callback", handler, callbackFilter)
Fluent Handler API
For more complex handler setups, the builder API provides a cleaner way to apply filters, set groups, and priorities.
client.OnMessage("", handler).
Private(). // Equivalent to IsPrivate
From(123, 456). // Equivalent to FromUsers
Group(1). // Set handler group
Priority(10). // Set execution priority
Register()
Builder Methods Reference
| Method | Description |
|---|
.Private() | Private chats only. |
.Groups() | Group chats only. |
.Channels() | Channels only. |
.From(ids...) | From specific users. |
.In(ids...) | In specific chats. |
.Filter(fs...) | Add any standard filter(s). |
.Group(id) | Assign to a specific handler group. |
.Priority(lvl) | Set priority (higher runs first). |
.Register() | Finalize and register the handler. |