ExGram

The ExGram.Router uses a declarative scope / filter / handle DSL to replace manual handle/2 pattern matching.

Dispatch Logic:

1. Order Matters: Scopes are evaluated top-to-bottom in the order they are declared.
2. AND Logic: All filters within a single scope must pass for the scope to match.
3. First Match Wins: The first matching leaf scope executes its handler, and dispatching stops.
4. Fallback: A scope defined without any filter matches everything. Place this at the bottom of your module to act as a catch-all fallback.

Handler Arities:

• 1-arity: Receives only the context. Use this for simple responses.
• 2-arity: Receives (update_info, context). Use this when you need to extract data (like text or callback data) directly from the parsed update tuple.

# 1-arity: receives only context
def start(context) do
  answer(context, "Welcome!")
end

# 2-arity: receives (update_info, context)
def echo({:text, text, _msg}, context) do
  answer(context, text)
end

The ExGram DSL uses a builder pattern to queue actions. DSL functions do not execute immediately; instead, they build up a list of actions on the context object.

Crucial Rules:

1. Return the context: You must return the updated context from your handler. If you don't return it, the queued actions will never be executed.
2. Immutability: Because Elixir is immutable, you must pass the updated context to each subsequent action in the chain (e.g., using the pipe operator |>).
3. Execution Order: Actions are executed sequentially after your handler function completes (Action 1 $\rightarrow$ Action 2 $\rightarrow$ Action 3).
4. Mixing DSL and Low-Level API: If you use the low-level ExGram.send_* functions inside a handler, they execute immediately, which might cause them to be sent before the DSL actions queued in the context. To run a low-level action after a DSL action, use on_result/2.

def handle({:command, "start", _msg}, context) do
  context
  |> answer("Welcome!")           # Action 1: queued
  |> answer("Here's a menu:")     # Action 2: queued
  |> answer_photo(photo_id)       # Action 3: queued
end
# After handler returns, ExGram executes: action 1 $\rightarrow$ action 2 $\rightarrow$ action 3

Key adapters determine how FSM state is scoped (who shares state with whom). You can set this using the key: option in use ExGram.FSM.

Examples

User-scoped (state follows user everywhere):

use ExGram.FSM, key: ExGram.FSM.Key.User, flows: [...]

Chat-scoped (shared state, e.g. group game sessions):

use ExGram.FSM, key: ExGram.FSM.Key.Chat, flows: [...]

Bot Init hooks allow you to run custom code during the bot's startup sequence, before it begins processing updates. They are ideal for tasks like fetching external configuration, pre-warming caches, or validating credentials.

A hook is a module that implements the ExGram.BotInit behaviour. The on_bot_init/1 callback is executed once during startup. Hooks run in a specific sequence:

1. ExGram.BotInit.GetMe (built-in, enabled by default)
2. ExGram.BotInit.SetupCommands (built-in, enabled if setup_commands: true)
3. Your custom hooks (in the order they are declared)
4. The init/1 callback on your bot module
5. The bot starts receiving updates

Data can be passed between hooks and to all subsequent handlers using the context.extra map.

defmodule MyApp.ConfigHook do
  @behaviour ExGram.BotInit

  @impl ExGram.BotInit
  def on_bot_init(opts) do
    # ... logic ...
    {:ok, %{app_config: config}}
  end
end

When using ExGram.Bot, your module follows this pattern:

• @bot :name - An internal identifier for your bot.
• use ExGram.Bot, [...] - Imports the framework. Common options include setup_commands: true (automatically registers commands with Telegram).
• command/1-2 - Declares commands (e.g., command("start") or command("help", description: "...")) that the bot is capable of handling.
• middleware/1 - Adds middleware to the processing pipeline (e.g., middleware(ExGram.Middleware.IgnoreUsername)).
• handle({:type, :name, _msg}, context) - The callback function used to process incoming updates (e.g., commands, messages).

defmodule MyBot.Bot do
  @bot :my_bot

  use ExGram.Bot,
    name: @bot,
    setup_commands: true

  command("start")
  command("help", description: "Print the bot's help")

  middleware(ExGram.Middleware.IgnoreUsername)

  def handle({:command, :start, _msg}, context) do
    answer(context, "Hi!")
  end

  def handle({:command, :help, _msg}, context) do
    answer(context, "Here is your help:")
  end
end