Behaviour for channel-specific mention detection and parsing.

Mention detection varies significantly across platforms. This behaviour defines how channels can implement platform-specific mention parsing while providing normalized output for the messaging pipeline.

Mention Structure

Parsed mentions follow a consistent structure:

%{
  user_id: "123456789",      # Platform's user ID
  username: "johndoe",       # Username (may be nil)
  offset: 0,                 # Byte offset in the message body
  length: 8                  # Length of the mention text
}

Implementation

Channels should implement this behaviour to enable mention detection:

defmodule MyApp.Channels.Telegram.Mentions do
  @behaviour Jido.Chat.Adapters.Mentions

  @impl true
  def parse_mentions(body, raw) do
    entities = raw["entities"] || []

    entities
    |> Enum.filter(&(&1["type"] == "mention" or &1["type"] == "text_mention"))
    |> Enum.map(fn entity ->
      %{
        user_id: to_string(entity["user"]["id"]),
        username: entity["user"]["username"],
        offset: entity["offset"],
        length: entity["length"]
      }
    end)
  end

  @impl true
  def was_mentioned?(raw, bot_id) do
    entities = raw["entities"] || []
    Enum.any?(entities, fn e ->
      e["type"] == "text_mention" and to_string(e["user"]["id"]) == bot_id
    end)
  end
end

Integration with MsgContext

The MsgContext struct includes fields populated by mention adapters:

• was_mentioned - Boolean indicating if the bot was mentioned
• mentions - List of parsed mention maps

Default Implementations

All callbacks are optional:

• parse_mentions/2 - Returns [] if not implemented
• strip_mentions/2 - Returns the original body if not implemented
• was_mentioned?/2 - Returns false if not implemented