TelegramEx behaviour (TelegramEx v1.3.0)

Defines a behaviour for Telegram bots and provides the main use macro.

use TelegramEx sets up callbacks, imports common helpers, registers the bot child spec, and adds fallback handlers.

Macro Options

:name (required) - bot identifier used for config lookup and FSM storage
:routers (optional) - router modules tried before the bot module

See Getting Started for setup and supervision examples, and Effects for builder pipeline error handling.

Summary

Types

context()

Context map passed to all handlers.

handler_result()

Return value from handlers.

Callbacks

handle_callback(callback, context)

Callback invoked when a callback query (inline button press) is received.

handle_message(message, context)

Callback invoked when a message is received.

Types

context()

@type context() :: %{
  :token => String.t(),
  :state => atom() | nil,
  :data => term(),
  optional(:message_thread_id) => integer(),
  optional(:payload) => map(),
  optional(:chat_id) => integer(),
  optional(:method) => String.t(),
  optional(:format) => :json | :multipart
}

Context map passed to all handlers.

Contains bot token, FSM state/data, and builder request data.

handler_result()

@type handler_result() ::
  :ok
  | :pass
  | TelegramEx.Effect.t()
  | {:transition, new_state :: atom()}
  | {:transition, new_state :: atom(), data :: term()}
  | {:stay, data :: term()}
  | {:error, reason :: term()}

Return value from handlers.

Builder pipelines return TelegramEx.Effect values. The server converts them to ordinary handler results before applying FSM transitions or logging errors.

Callbacks

handle_callback(callback, context)

@callback handle_callback(
  callback :: TelegramEx.Types.CallbackQuery.t(),
  context :: context()
) ::
  handler_result()

Callback invoked when a callback query (inline button press) is received.

Return a handler_result/0. See Messages and Media for callback examples.

handle_message(message, context)

@callback handle_message(message :: TelegramEx.Types.Message.t(), context :: context()) ::
  handler_result()

Callback invoked when a message is received.

Return a handler_result/0. See Getting Started for handler examples.