Event filters

Filters are used to filter events before they are passed to the handler. Filters are used to filter events by their type, by the user that triggered the event, by the community, by the channel, etc.

When a filter is used, the handler will only be called if the event passes the filter.

You can use multiple filters in a single handler, using the unary operators & and |.

To add a filter to a handler, add the filter as a parameter to the handler class.

Filter types

• self Filter messages generated by the same user. Example: @app.on_message(self)
• is_bot Filter messages coming from bots. Example: @app.on_message(is_bot)
• me Filter messages coming from your user. Example: @app.on_message(me)
• incoming Filter incoming messages. Messages that are sent to the users recipient. Example: @app.on_message(incoming)
• outgoing Filter outgoing messages. Messages that are sent by the user. Example: @app.on_message(outgoing)
• community Filter events coming from a specific community or list of communities. Accepts a single community_id or an array of ids. Example: @app.on_message(community("123456789")) or @app.on_message(community(["123456789", "987654321"]))
• channel Filter events coming from a specific channel or a list of channels. Accepts a single channel_id or an array of ids. Example: @app.on_message(channel("123456789")) or @app.on_message(channel(["123456789", "987654321"]))
• group Filter events coming from a specific group or a list of groups. Accepts a single group_id or an array of ids. Example: @app.on_message(group("123456789")) or @app.on_message(group(["123456789", "987654321"]))
• user Filter events coming from a specific user or a list of users. Accepts a single user_id or an array of ids. Example: @app.on_message(user("123456789")) or @app.on_message(user(["123456789", "987654321"]))
• text Filter messages that contain a specific text. Example: @app.on_message(text("hello")) will match messages that contain the text "hello"
• regexp Filter messages that match a specific regex. Example: @app.on_message(regex(r"^hello")) will match messages that start with "hello"
• message_type Filter messages that match a specific message type. Example: @app.on_message(message_type(0)) will match messages that are of type 0 (text), @app.on_message(message_type(1)) will match messages that are of type 1 (image), etc. (Available types are: 0 text, 1 image, 2 video, 3 audio, 7 document/file)
• audio: Filter for audio messages.
• document: Filter for document messages.
• video: Filter for video messages.
• photo: Filter for photo messages.
• sticker: Filter for sticker messages.

Filter examples

Normal filters

from swibots import Client, MessageHandler, BotContext, is_bot, community, channel, 

app = Client("token", "your bot description")

@app.on_message(is_bot & (community("123456789") | channel("123456")))
async def message_handler(ctx: BotContext[MessageEvent]):
    await m.reply_text(f"Thank you! I received your message: {ctx.event.message.message}")
    
app.run()

Regex filters

from swibots import Client, MessageEvent, BotContext, regexp

app = Client("token", "your bot description")

@app.on_message(regexp('hello (.*)'))
async def regex_handler(ctx: BotContext[MessageEvent]):
    print(ctx.event.message.matches) # List[re.Match]
    await ctx.event.message.respond(f"🦆 Hello {ctx.event.message.matches[0].group(1)}!")
    
app.run()

Custom Filters

You can use the filters.create() function to create your own custom filters!

from swibots import Client, filters, BotContext, MessageEvent

app = Client('TOKEN')

# A filter to match the starting of the message sent [case insensitive]
def hello_filter(data: str):
    async def func(flt, ctx):
        m = ctx.event.message
        if not m.message:
            return False
        return m.message.lower().startswith(flt.data.lower())
    return filters.create(func, data=data)

# add filter to message event
@app.on_message(hello_filter('hi'))
async def custom_filters(ctx: BotContext[MessageEvent]):
    await ctx.event.message.reply_text("Hello user 🤖!")