Skip to main content

​
Overview

Filters allow you to specify conditions that messages or callbacks must meet before handlers execute. They help you write cleaner code by avoiding manual condition checking.

​
Basic Filters

​
Chat Type Filters

// Private chats only
client.On("message", handler, telegram.FilterPrivate)

// Groups only
client.On("message", handler, telegram.FilterGroup)

// Channels only
client.On("message", handler, telegram.FilterChannel)

​
Message Type Filters

// Media messages
client.On("message", handler, telegram.FilterMedia)

// Commands
client.On("message", handler, telegram.FilterCommand)

// Replies
client.On("message", handler, telegram.FilterReply)

// Forwarded messages
client.On("message", handler, telegram.FilterForward)

// Messages from bots
client.On("message", handler, telegram.FilterFromBot)

// Mentions
client.On("message", handler, telegram.FilterMention)

// Edited messages
client.On("message", handler, telegram.FilterEdited)

​
Direction Filters

// Outgoing messages (sent by you)
client.On("message", handler, telegram.FilterOutgoing)

// Incoming messages (received)
client.On("message", handler, telegram.FilterIncoming)

​
Media Filters

​
Specific Media Types

// Photo messages
client.On("message", handler, telegram.FilterPhoto)

// Video messages
client.On("message", handler, telegram.FilterVideo)

// Document messages
client.On("message", handler, telegram.FilterDocument)

// Audio messages
client.On("message", handler, telegram.FilterAudio)

// Sticker messages
client.On("message", handler, telegram.FilterSticker)

// Animation/GIF messages
client.On("message", handler, telegram.FilterAnimation)

// Voice messages
client.On("message", handler, telegram.FilterVoice)

// Video notes (round videos)
client.On("message", handler, telegram.FilterVideoNote)

// Contact messages
client.On("message", handler, telegram.FilterContact)

// Location messages
client.On("message", handler, telegram.FilterLocation)

// Venue messages
client.On("message", handler, telegram.FilterVenue)

// Poll messages
client.On("message", handler, telegram.FilterPoll)

​
Multiple Media Types

// Accept multiple media types
client.On("message", handler, 
    telegram.FilterMediaTypes("photo", "video", "animation"))

​
Peer Filters

​
Filter by Users

// Specific users only
client.On("message", handler, telegram.FilterUsers(123456, 789012))

// Blacklist users
filter := telegram.FilterUsers(123456).AsBlacklist()
client.On("message", handler, filter)

​
Filter by Chats

// Specific chats only
client.On("message", handler, telegram.FilterChats(-1001234567890))

// Multiple chats
client.On("message", handler, 
    telegram.FilterChats(-1001234567890, -1009876543210))

​
Filter by Channels

// Specific channels only
client.On("message", handler, telegram.FilterChannels(-1001234567890))

​
Text Filters

​
Text Length

// Minimum text length
client.On("message", handler, telegram.FilterMinLength(10))

// Maximum text length
client.On("message", handler, telegram.FilterMaxLength(100))

// Messages with text
client.On("message", handler, telegram.Filter{}.WithText())

​
Combining Filters

​
Using Multiple Filters

// Private chats with photos
client.On("message", handler, 
    telegram.FilterPrivate, 
    telegram.FilterPhoto)

// Groups with commands
client.On("message", handler, 
    telegram.FilterGroup, 
    telegram.FilterCommand)

// Private videos from specific users
client.On("message", handler,
    telegram.FilterPrivate,
    telegram.FilterVideo,
    telegram.FilterUsers(123456, 789012))

​
AND Logic

Combine multiple filters with AND logic: 
filter := telegram.FilterAnd(
    telegram.FilterPrivate,
    telegram.FilterPhoto,
    telegram.FilterMinLength(5),
)
client.On("message", handler, filter)

​
OR Logic

Combine multiple filters with OR logic: 
filter := telegram.FilterOr(
    telegram.FilterPhoto,
    telegram.FilterVideo,
    telegram.FilterAnimation,
)
client.On("message", handler, filter)

​
NOT Logic

Negate a filter: 
// Not from bots
filter := telegram.FilterNot(telegram.FilterFromBot)
client.On("message", handler, filter)

// Not in groups
filter := telegram.FilterNot(telegram.FilterGroup)
client.On("message", handler, filter)

​
Custom Filters

​
Function-Based Filters

// Custom filter function
client.On("message", handler, telegram.FilterFunc(func(m *telegram.NewMessage) bool {
    return len(m.Text()) > 10 && m.SenderID() != 0
}))

// For callbacks
client.On("callback", callbackHandler, telegram.FilterFuncCallback(func(c *telegram.CallbackQuery) bool {
    return c.SenderID() == adminID
}))

​
Filter Builder

​
Chaining Filter Methods

filter := telegram.NewFilter().
    IsPrivate().
    WithPhoto().
    MinLen(5).
    FromUsers(123456, 789012)

client.On("message", handler, filter)

​
All Builder Methods

filter := telegram.NewFilter().
    IsPrivate().
    IsGroup().
    IsChannel()

​
Practical Examples

​
Admin-Only Commands

adminFilter := telegram.FilterFunc(func(m *telegram.NewMessage) bool {
    adminIDs := []int64{123456, 789012}
    for _, id := range adminIDs {
        if m.SenderID() == id {
            return true
        }
    }
    return false
})

client.On("cmd:ban", func(m *telegram.NewMessage) error {
    m.Reply("User banned!")
    return nil
}, adminFilter)

​
Photo/Video Only in Private

filter := telegram.FilterAnd(
    telegram.FilterPrivate,
    telegram.FilterOr(
        telegram.FilterPhoto,
        telegram.FilterVideo,
    ),
)

client.On("message", func(m *telegram.NewMessage) error {
    m.Reply("Nice photo/video!")
    return nil
}, filter)

​
Long Messages in Groups

client.On("message", func(m *telegram.NewMessage) error {
    m.Reply("Please keep messages short in groups")
    return nil
}, telegram.FilterGroup, telegram.FilterMinLength(500))

​
Blacklist Specific Users

filter := telegram.FilterUsers(spammerID1, spammerID2).AsBlacklist()

client.On("message", func(m *telegram.NewMessage) error {
    // This handler won't execute for blacklisted users
    return nil
}, filter)

​
Media Albums Only

client.On("album", func(a *telegram.Album) error {
    a.Messages[0].Reply("Received %d media items", len(a.Messages))
    return nil
})

​
Callback from Specific Button

client.On("callback:btn_approve", func(c *telegram.CallbackQuery) error {
    c.Answer("Approved!")
    return nil
}, telegram.FilterFuncCallback(func(c *telegram.CallbackQuery) bool {
    return c.SenderID() == adminID
}))

​
Filter Reference

​
Complete Filter List

FilterDescription
FilterPrivatePrivate chats only
FilterGroupGroups only
FilterChannelChannels only
FilterMediaAny media message
FilterCommandCommand messages
FilterReplyReply messages
FilterForwardForwarded messages
FilterFromBotMessages from bots
FilterMentionMessages with mentions
FilterOutgoingOutgoing messages
FilterIncomingIncoming messages
FilterEditedEdited messages
FilterPhotoPhoto messages
FilterVideoVideo messages
FilterDocumentDocument messages
FilterAudioAudio messages
FilterStickerSticker messages
FilterAnimationAnimation/GIF messages
FilterVoiceVoice messages
FilterVideoNoteVideo note messages
FilterContactContact messages
FilterLocationLocation messages
FilterVenueVenue messages
FilterPollPoll messages

​
Best Practices

Use Built-in Filters

Prefer built-in filters over custom logic when possible

Combine Filters

Use AND/OR logic to create complex conditions

Early Filtering

Filter as early as possible to improve performance

Custom Filters

Use FilterFunc for complex custom logic

Blacklists

Use AsBlacklist() to exclude specific users/chats

Test Filters

Test your filters thoroughly with different message types

​
Next Steps

Event Handlers

Back to event handlers

Update Types

Explore update types

Examples

See practical examples