ex_gram

# Handling Updates

This guide explains how to handle different types of updates from Telegram in your ExGram bot.

## The `handle/2` Function

Every bot must implement the `c:ExGram.Handler.handle/2` function. It receives:

1. **Update tuple** - Different tuple patterns for different update types
2. **Context** - A `t:ExGram.Cnt.t/0` struct with update information

```elixir
def handle(update_tuple, context) do
  # Process the update and return context
  context
end
```

The context contains:
- `update` - The full [Update](https://core.telegram.org/bots/api#update) object
- `name` - Your bot's name (important for multiple bots)
- `bot_info` - You bot's information, extracted with `ExGram.get_me/1` at startup
- `extra` - Custom data from middlewares
- Internal fields used by ExGram

## Update Patterns

ExGram parses updates into convenient tuples for pattern matching.

### Commands

Matches messages starting with `/command` or `/command@your_bot`.

```elixir
def handle({:command, "start", msg}, context) do
  answer(context, "Welcome! You sent: #{msg}")
end

def handle({:command, "help", _msg}, context) do
  answer(context, """
  Available commands:
  /start - Start the bot
  /help - Show this help
  /settings - Configure settings
  """)
end
```

The `msg` parameter contains any text after the command:
- `/start` → `msg = ""`
- `/start hello world` → `msg = "hello world"`

You can also declare commands at the module level:

```elixir
command("start")
command("help", description: "Show help message")
command("settings", description: "Configure your settings")
```

With `setup_commands: true`, these are automatically registered with Telegram.

And, once you declare them, you will receive the commands as atoms:

```elixir
def handle({:command, :start, msg}, context) do
  # ...
end

def handle({:command, :help, _msg}, context)
def handle({:command, :settings, _msg}, context)

# You can still handle not defined commands
def handle({:command, "othercommand", _msg}, context)
```

This is really important if you want to provide command translations or commands for different roles.

Check the [commands guide](./commands.md) if you want to know more.

### Plain Text

Matches regular text messages (respects [privacy mode](https://core.telegram.org/bots#privacy-mode)).

```elixir
def handle({:text, text, message}, context) do
  cond do
    String.contains?(text, "hello") ->
      answer(context, "Hello to you too!")
    
    String.length(text) > 100 ->
      answer(context, "That's a long message!")
    
    true ->
      answer(context, "You said: #{text}")
  end
end
```

### Regex Patterns

Define regex patterns at module level and match against them:

```elixir
defmodule MyBot.Bot do
  use ExGram.Bot, name: :my_bot

  # Define regex patterns
  regex(:email, ~r/\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b/)
  regex(:phone, ~r/\b\d{3}[-.]?\d{3}[-.]?\d{4}\b/)

  def handle({:regex, :email, message}, context) do
    answer(context, "I detected an email address in your message!")
  end

  def handle({:regex, :phone, message}, context) do
    answer(context, "That looks like a phone number!")
  end
end
```

### Callback Queries

Handles button presses from inline keyboards.

```elixir
def handle({:callback_query, %{data: "button_" <> id} = callback}, context) do
  context
  |> answer_callback("Processing button #{id}")
  |> answer("You clicked button #{id}")
end

def handle({:callback_query, %{data: "delete"}}, context) do
  context
  |> answer_callback("Deleting message...")
  |> delete()
end
```

See [Sending Messages](sending-messages.md) for creating inline keyboards.

### Inline Queries

Handles inline queries (e.g., `@yourbot search term`).

```elixir
def handle({:inline_query, query}, context) do
  results = [
    %{
      type: "article",
      id: "1",
      title: "Result 1",
      input_message_content: %{message_text: "You selected result 1"}
    },
    %{
      type: "article",
      id: "2",
      title: "Result 2",
      input_message_content: %{message_text: "You selected result 2"}
    }
  ]

  answer_inline_query(context, results)
end
```

### Location Messages

Handles location sharing.

```elixir
def handle({:location, %ExGram.Model.Location{latitude: lat, longitude: lon}}, context) do
  answer(context, "You're at #{lat}, #{lon}. Thanks for sharing!")
end
```

### Edited Messages

Handles message edits.

```elixir
def handle({:edited_message, edited_msg}, context) do
  # You can choose to process edited messages differently
  # or ignore them entirely
  Logger.info("Message #{edited_msg.message_id} was edited")
  context
end
```

### Generic Message Handler

Catches any message that doesn't match other patterns.

```elixir
def handle({:message, message}, context) do
  cond do
    message.photo ->
      answer(context, "Nice photo!")
    
    message.document ->
      answer(context, "Thanks for the document!")
    
    message.sticker ->
      answer(context, "Cool sticker!")
    
    message.voice ->
      answer(context, "I received your voice message!")
    
    true ->
      answer(context, "I received your message, but I'm not sure what to do with it.")
  end
end
```

### Default Handler

Catches all other updates.

ExGram will slowly add more specific handlers to make it easier to differentiate all the possible update types.


```elixir
def handle({:update, update}, context) do
  Logger.debug("Received unhandled update: #{inspect(update)}")
  context
end
```

## The Context (`t:ExGram.Cnt.t/0`)

The context struct contains:

```elixir
%ExGram.Cnt{
  update: %ExGram.Model.Update{},  # Full Telegram update, useful to get more information about the update in specific handlers
  name: :my_bot,                    # Your bot's name (the one from "use ExGram.Bot, name: :my_bot")
  bot_info: %ExGram.Model.User{} | nil, # The bot's information, extracted with ExGram.get_me at bot's startup
  extra: %{}                        # Custom data from middlewares
  # More fields used internally
}
```

### Adding Extra Data

Middlewares can add custom data to `context.extra`:

```elixir
# In a middleware
use ExGram.Middleware

def call(context, _opts) do
  user_id = extract_id(context)
  extra_data = %{user_role: fetch_user_role(user_id)}
  
  add_extra(context, extra_data)
end

# In your handler
def handle({:command, "admin", _msg}, context) do
  case context.extra[:user_role] do
    :admin -> answer(context, "Admin panel: ...")
    _ -> answer(context, "Access denied")
  end
end
```

Read more about middlewares in [this guide](./middlewares.md)

## The `c:ExGram.Handler.init/1` Callback

The optional `c:ExGram.Handler.init/1` callback runs once before processing updates. Use it to initialize your bot:

```elixir
def init(opts) do
  # opts contains [:bot, :token]
  ExGram.set_my_description!(
    description: "This bot helps you manage tasks",
    bot: opts[:bot]
  )
  
  ExGram.set_my_name!(
    name: "TaskBot",
    token: opts[:token]
  )
  
  # Do some logic you need before starting your bots
  # MyBot.notify_admins_restart(opts[:bot])
  
  :ok
end
```

**Note:** If you use `setup_commands: true`, commands are automatically registered. Use `init/1` for additional setup.

## Pattern Matching Tips

### Multiple Clauses

Use multiple function clauses for clean code:

```elixir
def handle({:command, :start, _}, context), do: answer(context, "Welcome!")
def handle({:command, :help, _}, context), do: show_help(context)
def handle({:command, :about, _}, context), do: show_about(context)

def handle({:callback_query, %{data: "yes"}}, context) do
  answer_callback(context, "You chose yes!")
end

def handle({:callback_query, %{data: "no"}}, context) do
  answer_callback(context, "You chose no!")
end

def handle({:text, text, _msg}, context) when is_binary(text) do
  answer(context, "Echo: #{text}")
end

def handle(_update, context), do: context
```

### Guards

Use guards for additional filtering:

```elixir
def handle({:text, text, _msg}, context) when byte_size(text) > 500 do
  answer(context, "Please send shorter messages (max 500 characters)")
end

def handle({:text, text, _msg}, context) when text in ["hi", "hello", "hey"] do
  answer(context, "Hello there!")
end
```

### Extracting Data

Pattern match to extract specific fields:

```elixir
def handle({:message, %{from: %{id: user_id, username: username}}}, context) do
  answer(context, "Hello @#{username} (ID: #{user_id})")
end

def handle({:callback_query, %{from: user, data: data}}, context) do
  Logger.info("User #{user.id} clicked: #{data}")
  answer_callback(context, "Got it!")
end
```

## Next Steps

- [Sending Messages](sending-messages.md) - Learn the DSL for building responses
- [Message Entities](message-entities.md) - Format messages without Markdown or HTML
- [Middlewares](middlewares.md) - Add preprocessing logic to your bot
- [Low-Level API](low-level-api.md) - Direct API calls for complex scenarios
- [Cheatsheet](cheatsheet.md) - Quick reference for all patterns