MTGo

Appearance

MTGo Filters API ​

Filters determine which updates a handler receives. A filter is a function that inspects an update context and returns true if the update should be handled.

Filter Type ​

go
type Filter func(ctx *Context) bool

Composition Methods ​

Filters can be combined using boolean logic.

And ​

go
func (f Filter) And(other Filter) Filter

Returns a filter that matches only when both filters match.

go
filter := filters.Incoming.And(filters.Photo)
dp.Handle(filter, photoHandler)

Or ​

go
func (f Filter) Or(other Filter) Filter

Returns a filter that matches when either filter matches.

go
filter := filters.Audio.Or(filters.Video)
dp.Handle(filter, mediaHandler)

Not ​

go
func (f Filter) Not() Filter

Returns a filter that matches when the original filter does not match.

go
filter := filters.Command("start").Not()
dp.Handle(filter, nonStartHandler)

Custom Filter ​

Create ​

go
func Create(fn func(*Client, *Context) bool) Filter

Creates a custom filter from a function that has access to both the client and context.

go
vipFilter := filters.Create(func(c *mtgo.Client, ctx *mtgo.Context) bool {
    return ctx.Sender().Username == "vip_user"
})
dp.Handle(vipFilter, vipHandler)

NewCommand ​

go
func NewCommand(commands []string, prefixes []string, caseSensitive bool) Filter

Creates a command filter with custom prefixes and case sensitivity.

ParameterTypeDescription
commands[]stringCommand names without prefix
prefixes[]stringPrefix characters (e.g. ["/", "!"])
caseSensitiveboolWhether matching is case-sensitive
go
cmdFilter := filters.NewCommand([]string{"start", "help"}, []string{"/", "!"}, false)
dp.Handle(cmdFilter, startOrHelpHandler)

Variable Filters ​

Universal ​

FilterDescription
AllMatches every update
MeMatches updates about the current user
BotMatches updates from bots

Direction ​

FilterDescription
IncomingMessages received from others
OutgoingMessages sent by the current user

Message Content ​

FilterDescription
CaptionMessages with a caption
AudioAudio file messages
VideoVideo messages
AnimationGIF / animation messages
VoiceVoice note messages
VideoNoteRound video messages
StickerSticker messages
PhotoPhoto messages
DocumentDocument/file messages
ContactContact messages
LocationLocation messages
LiveLocationLive location messages
VenueVenue messages
WebPageMessages with web page previews
PollPoll messages
DiceDice messages
GameGame messages
GiveawayGiveaway messages
GiveawayWinnersGiveaway winner announcements
StoryStory messages
PaidMediaPaid media messages
InvoiceInvoice messages
MediaGroupAlbum / grouped media messages
MediaSpoilerMessages with media spoiler
MediaAny media attachment
HasMediaMessages that have any media

Chat Type ​

FilterDescription
PrivatePrivate (1-on-1) chats
GroupBasic group chats
ChannelChannel messages
ForumForum / topic chats
BusinessBusiness connection messages
GuestMessageGuest messages in business chats

Message State ​

FilterDescription
ServiceService messages
ScheduledScheduled messages
FromScheduledMessages created from a schedule
PaidMessagePaid messages
LinkedChannelMessages from linked channels
ForwardedForwarded messages
ReplyMessages that are replies
MentionedMessages mentioning the user
ViaBotMessages sent via inline bot
PinnedPinned messages
DirectDirect (non-forwarded) messages
QuoteMessages that quote another
AdminMessages from chat admins

Service Events ​

FilterDescription
NewChatMembersNew members joined
LeftChatMemberA member left
NewChatTitleChat title changed
NewChatPhotoChat photo changed
DeleteChatPhotoChat photo deleted
GroupChatCreatedGroup chat created
SupergroupChatCreatedSupergroup created
ChannelChatCreatedChannel created
MigrateToChatIDChat migrated to supergroup
MigrateFromChatIDMigrated from group
PinnedMessageMessage pinned
GameHighScoreGame high score
VideoChatStartedVideo chat started
VideoChatEndedVideo chat ended
VideoChatMembersInvitedMembers invited to video chat
SuccessfulPaymentSuccessful payment received
ReplyKeyboardReply keyboard shown
InlineKeyboardInline keyboard shown
SelfDestructionSelf-destructing message

Function Filters ​

Text ​

go
func Text(s string) Filter

Matches messages with exact text content.

go
dp.Handle(filters.Text("hello"), helloHandler)

Command ​

go
func Command(commands ...string) Filter

Matches command messages. Supports multiple commands.

go
dp.Handle(filters.Command("start", "restart"), startHandler)
dp.Handle(filters.Command("help"), helpHandler)

Regex ​

go
func Regex(pattern string) Filter

Matches messages whose text matches a regular expression.

go
dp.Handle(filters.Regex(`(?i)^/echo\s+(.+)$`), echoHandler)

User ​

go
func User(userIDs ...int64) Filter

Matches messages from specific user IDs.

go
dp.Handle(filters.User(12345678, 87654321), trustedHandler)

Chat ​

go
func Chat(chatIDs ...int64) Filter

Matches messages from specific chat IDs.

go
dp.Handle(filters.Chat(-1001234567890), groupHandler)

Topic ​

go
func Topic(topicIDs ...int32) Filter

Matches messages in specific forum topics.

go
dp.Handle(filters.Topic(42), topicHandler)

SenderChat ​

go
func SenderChat(chatIDs ...int64) Filter

Matches messages sent on behalf of specific chats (e.g., channel posts in linked groups).

go
dp.Handle(filters.SenderChat(-1001234567890), channelHandler)

CallbackData ​

go
func CallbackData(data string) Filter

Matches callback queries with exact data.

go
dp.Handle(filters.CallbackData("approve"), approveHandler)

CallbackRegex ​

go
func CallbackRegex(pattern string) Filter

Matches callback queries whose data matches a regular expression.

go
dp.Handle(filters.CallbackRegex(`^page:(\d+)$`), pageHandler)

InlineQueryText ​

go
func InlineQueryText(s string) Filter

Matches inline queries containing specific text.

go
dp.Handle(filters.InlineQueryText("search"), searchHandler)

ChatActionFilter ​

go
func ChatActionFilter(chatID int64) Filter

Matches chat action updates for a specific chat.

go
dp.Handle(filters.ChatActionFilter(-1001234567890), actionHandler)

Combining Filters ​

Filters can be composed to create complex matching logic:

go
dp.Handle(
    filters.Incoming.And(
        filters.Private.Or(filters.Group),
    ).And(
        filters.Command("start"),
    ),
    startHandler,
)

dp.Handle(
    filters.Media.And(filters.Incoming).Not(),
    outgoingMediaHandler,
)

dp.Handle(
    filters.NewChatMembers.And(filters.Group),
    welcomeHandler,
)

Released under the Apache-2.0 License.