Behaviour for ExGram.Router filters.

A filter is a module that decides whether a particular scope or handler should match a given update. Filters receive the parsed update info tuple (the same first argument ExGram passes to handle/2), the full context, and any opts provided in the filter declaration.

Callbacks

call/3 (required)

Returns true if the filter passes (the scope should be considered) or false if it fails (skip this scope).

scope_extra/2 (optional)

Called by the dispatcher after call/3 returns true, only when the filter implements this callback. Returns a map that is merged into context.extra before recursing into child scopes. This lets a filter enrich the context for its children without affecting sibling scopes.

Because Elixir data is immutable, enrichment is automatically isolated: siblings receive the original context from their parent's caller, not the enriched copy.

Example – basic filter

defmodule MyApp.Filters.AdminOnly do
  @behaviour ExGram.Router.Filter

  def call(_update_info, context, _opts) do
    {:ok, user} = ExGram.Dsl.extract_user(context)
    user.id in Application.fetch_env!(:my_app, :admin_ids)
  end
end

scope do
  filter MyApp.Filters.AdminOnly
  handle &MyBot.admin_panel/1
end

Example – filter with propagation via scope_extra/2

The built-in :callback_query filter implements scope_extra/2 and supports the propagate: true option. When a parent scope sets propagate: true, child scopes see an accumulated prefix in context.extra.__exgram_router__.text_prefix so they can match against the suffix of the callback data:

scope do
  filter :callback_query, prefix: "proj:", propagate: true

  scope do
    filter :callback_query, "change"   # matches "proj:change"
    handle &Handlers.change_project/1
  end
end