telega · telega

get_api_config

pub fn get_api_config(
  telega: Telega(session, error),
) -> client.TelegramClient

Helper to get the config for API requests.

get_me

</>

pub fn get_me(telega: Telega(session, error)) -> types.User

Get the bot’s information.

get_session

</>

pub fn get_session(ctx: bot.Context(session, error)) -> session

Get session for the current context.

get_supervisor_pid

</>

pub fn get_supervisor_pid(
  telega: Telega(session, error),
) -> process.Pid

Get the supervisor PID for the running bot instance.

handle_update

</>

pub fn handle_update(
  telega: Telega(session, error),
  raw_update: types.Update,
) -> Bool

Handle an update.

This function is useful when you want to handle updates in your own way.

init

</>

pub fn init(
  builder: TelegaBuilder(session, error),
) -> Result(Telega(session, error), error.TelegaError)

Initialize the bot for webhook mode with a supervision tree.

init_for_polling

</>

pub fn init_for_polling(
  builder: TelegaBuilder(session, error),
) -> Result(Telega(session, error), error.TelegaError)

Initialize the bot for long polling with a supervision tree. Includes a supervised polling worker that auto-starts.

init_for_polling_nil_session

</>

pub fn init_for_polling_nil_session(
  builder: TelegaBuilder(Nil, error),
) -> Result(Telega(Nil, error), error.TelegaError)

Initialize the bot for long polling with nil session.

is_secret_token_valid

</>

pub fn is_secret_token_valid(
  telega: Telega(session, error),
  token: String,
) -> Bool

Check if a secret token is valid.

Useful if you plan to implement own adapter.

is_webhook_path

</>

pub fn is_webhook_path(
  telega: Telega(session, error),
  path: String,
) -> Bool

Check if a path is the webhook path for the bot.

Useful if you plan to implement own adapter.

log_context

</>

pub fn log_context(
  ctx: bot.Context(session, error),
  prefix: String,
  fun: fn(bot.Context(session, error)) -> Result(
    bot.Context(session, error),
    error,
  ),
) -> Result(bot.Context(session, error), error)

Add logging context to the current context.

log_error

</>

pub fn log_error(
  ctx: bot.Context(session, error),
  message: String,
) -> Nil

log_info

</>

pub fn log_info(
  ctx: bot.Context(session, error),
  message: String,
) -> Nil

Context helpers for logging

new

</>

pub fn new(
  api_client api_client: client.TelegramClient,
  url server_url: String,
  webhook_path webhook_path: String,
  secret_token secret_token: option.Option(String),
) -> TelegaBuilder(session, error)

Create a new Telega instance.

Requires an api_client created by an adapter package like telega_httpc or telega_hackney.

new_for_polling

</>

pub fn new_for_polling(
  api_client api_client: client.TelegramClient,
) -> TelegaBuilder(session, error)

Create a new Telega instance optimized for long polling.

Requires an api_client created by an adapter package like telega_httpc or telega_hackney. This is a convenience function for polling bots that don’t need webhook configuration.

set_allowed_updates

</>

pub fn set_allowed_updates(
  builder: TelegaBuilder(session, error),
  updates: List(String),
) -> TelegaBuilder(session, error)

Set allowed updates for webhook.

set_api_client

</>

pub fn set_api_client(
  builder: TelegaBuilder(session, error),
  client: client.TelegramClient,
) -> TelegaBuilder(session, error)

Set a custom API client.

set_certificate

</>

pub fn set_certificate(
  builder: TelegaBuilder(session, error),
  cert: types.File,
) -> TelegaBuilder(session, error)

Set certificate for webhook.

set_drop_pending_updates

</>

pub fn set_drop_pending_updates(
  builder: TelegaBuilder(session, error),
  drop: Bool,
) -> TelegaBuilder(session, error)

Set whether to drop pending updates.

set_ip_address

</>

pub fn set_ip_address(
  builder: TelegaBuilder(session, error),
  ip: String,
) -> TelegaBuilder(session, error)

Set IP address for webhook.

set_max_connections

</>

pub fn set_max_connections(
  builder: TelegaBuilder(session, error),
  max: Int,
) -> TelegaBuilder(session, error)

Set max connections for webhook.

shutdown

</>

pub fn shutdown(telega: Telega(session, error)) -> Nil

Graceful shutdown — stops supervisor, cascading to all children. Children are stopped in reverse start order: polling → bot → chat_factory.

start_polling_default

</>

pub fn start_polling_default(
  telega: Telega(session, error),
) -> Result(polling.Poller, error.TelegaError)

Start polling with default configuration for a Telega instance. This is useful when you want to manually start polling outside the supervision tree.

wait_any

</>

pub fn wait_any(
  ctx ctx: bot.Context(session, error),
  or handle_else: option.Option(bot.Handler(session, error)),
  timeout timeout: option.Option(Int),
  continue handler: fn(bot.Context(session, error), update.Update) -> Result(
    bot.Context(session, error),
    error,
  ),
) -> Result(bot.Context(session, error), error)

Pauses the current chat actor’s handler and waits for any update. Other chats and users continue to be handled concurrently.

See conversation

wait_audio

</>

pub fn wait_audio(
  ctx ctx: bot.Context(session, error),
  or handle_else: option.Option(bot.Handler(session, error)),
  timeout timeout: option.Option(Int),
  continue continue: fn(bot.Context(session, error), types.Audio) -> Result(
    bot.Context(session, error),
    error,
  ),
) -> Result(bot.Context(session, error), error)

Pauses the current chat actor’s handler and waits for an audio message. Other chats and users continue to be handled concurrently.

See conversation

wait_callback_query

</>

pub fn wait_callback_query(
  ctx ctx: bot.Context(session, error),
  filter filter: option.Option(bot.CallbackQueryFilter),
  or handle_else: option.Option(bot.Handler(session, error)),
  timeout timeout: option.Option(Int),
  continue continue: fn(
    bot.Context(session, error),
    String,
    String,
  ) -> Result(bot.Context(session, error), error),
) -> Result(bot.Context(session, error), error)

Pauses the current chat actor’s handler and waits for a callback query. Other chats and users continue to be handled concurrently.

See conversation

wait_choice

</>

pub fn wait_choice(
  ctx ctx: bot.Context(session, error),
  options options: List(#(String, a)),
  or handle_else: option.Option(bot.Handler(session, error)),
  timeout timeout: option.Option(Int),
  continue continue: fn(bot.Context(session, error), a) -> Result(
    bot.Context(session, error),
    error,
  ),
) -> Result(bot.Context(session, error), error)

Wait for user choice from inline keyboard.

This function creates an inline keyboard with provided options and waits for user to select one.

Examples

use ctx, color <- wait_choice(
  ctx,
  [
    #("🔴 Red", Red),
    #("🔵 Blue", Blue),
    #("🟢 Green", Green),
  ],
  or: None,
  timeout: None,
)

See conversation

wait_command

</>

pub fn wait_command(
  ctx ctx: bot.Context(session, error),
  command command: String,
  or handle_else: option.Option(bot.Handler(session, error)),
  timeout timeout: option.Option(Int),
  continue continue: fn(
    bot.Context(session, error),
    update.Command,
  ) -> Result(bot.Context(session, error), error),
) -> Result(bot.Context(session, error), error)

Pauses the current chat actor’s handler and waits for a specific command. Other chats and users continue to be handled concurrently.

See conversation

wait_commands

</>

pub fn wait_commands(
  ctx ctx: bot.Context(session, error),
  commands commands: List(String),
  or handle_else: option.Option(bot.Handler(session, error)),
  timeout timeout: option.Option(Int),
  continue continue: fn(
    bot.Context(session, error),
    update.Command,
  ) -> Result(bot.Context(session, error), error),
) -> Result(bot.Context(session, error), error)

Pauses the current chat actor’s handler and waits for one of the specified commands. Other chats and users continue to be handled concurrently.

See conversation

wait_email

</>

pub fn wait_email(
  ctx ctx: bot.Context(session, error),
  or handle_else: option.Option(bot.Handler(session, error)),
  timeout timeout: option.Option(Int),
  continue continue: fn(bot.Context(session, error), String) -> Result(
    bot.Context(session, error),
    error,
  ),
) -> Result(bot.Context(session, error), error)

Wait for email with validation.

This function waits for user to send text that matches email pattern.

If validation fails and or handler is provided, it will be called. Otherwise, the function will keep waiting for valid input.

Examples

use ctx, email <- wait_email(
  ctx,
  or: Some(bot.HandleText(fn(ctx, invalid) {
    reply.with_text(ctx, "Invalid email format. Try again.")
  })),
  timeout: None,
)

See conversation

wait_for

</>

pub fn wait_for(
  ctx ctx: bot.Context(session, error),
  filter filter: fn(update.Update) -> Bool,
  or handle_else: option.Option(bot.Handler(session, error)),
  timeout timeout: option.Option(Int),
  continue continue: fn(
    bot.Context(session, error),
    update.Update,
  ) -> Result(bot.Context(session, error), error),
) -> Result(bot.Context(session, error), error)

Wait for update matching custom filter.

This function waits for any update that passes the provided filter function.

Examples

use ctx, photo_update <- wait_for(
  ctx,
  filter: fn(upd) {
    case upd {
      update.PhotoUpdate(..) -> True
      _ -> False
    }
  },
  or: Some(bot.HandleAll(fn(ctx, wrong_update) {
    reply.with_text(ctx, "Please send a photo")
  })),
  timeout: Some(60_000),
)

See conversation

wait_hears

</>

pub fn wait_hears(
  ctx ctx: bot.Context(session, error),
  hears hears: bot.Hears,
  or handle_else: option.Option(bot.Handler(session, error)),
  timeout timeout: option.Option(Int),
  continue continue: fn(bot.Context(session, error), String) -> Result(
    bot.Context(session, error),
    error,
  ),
) -> Result(bot.Context(session, error), error)

Pauses the current chat actor’s handler and waits for a message that matches the given Hears. Other chats and users continue to be handled concurrently.

See conversation

wait_message

</>

pub fn wait_message(
  ctx ctx: bot.Context(session, error),
  or handle_else: option.Option(bot.Handler(session, error)),
  timeout timeout: option.Option(Int),
  continue continue: fn(
    bot.Context(session, error),
    types.Message,
  ) -> Result(bot.Context(session, error), error),
) -> Result(bot.Context(session, error), error)

Pauses the current chat actor’s handler and waits for any message. Other chats and users continue to be handled concurrently.

See conversation

wait_number

</>

pub fn wait_number(
  ctx ctx: bot.Context(session, error),
  min min: option.Option(Int),
  max max: option.Option(Int),
  or handle_else: option.Option(bot.Handler(session, error)),
  timeout timeout: option.Option(Int),
  continue continue: fn(bot.Context(session, error), Int) -> Result(
    bot.Context(session, error),
    error,
  ),
) -> Result(bot.Context(session, error), error)

Wait for a number with validation.

This function waits for user to send text that can be parsed as an integer, with optional min/max validation.

If validation fails and or handler is provided, it will be called. Otherwise, the function will keep waiting for valid input.

Examples

use ctx, age <- wait_number(
  ctx,
  min: Some(0),
  max: Some(120),
  or: Some(bot.HandleText(fn(ctx, invalid) {
    reply.with_text(ctx, "Please enter age between 0 and 120")
  })),
  timeout: None,
)

See conversation

wait_photos

</>

pub fn wait_photos(
  ctx ctx: bot.Context(session, error),
  or handle_else: option.Option(bot.Handler(session, error)),
  timeout timeout: option.Option(Int),
  continue continue: fn(
    bot.Context(session, error),
    List(types.PhotoSize),
  ) -> Result(bot.Context(session, error), error),
) -> Result(bot.Context(session, error), error)

Pauses the current chat actor’s handler and waits for photos. Other chats and users continue to be handled concurrently.

See conversation

wait_text

</>

pub fn wait_text(
  ctx ctx: bot.Context(session, error),
  or handle_else: option.Option(bot.Handler(session, error)),
  timeout timeout: option.Option(Int),
  continue continue: fn(bot.Context(session, error), String) -> Result(
    bot.Context(session, error),
    error,
  ),
) -> Result(bot.Context(session, error), error)

Pauses the current chat actor’s handler and waits for a text message. Other chats and users continue to be handled concurrently.

See conversation

wait_video

</>

pub fn wait_video(
  ctx ctx: bot.Context(session, error),
  or handle_else: option.Option(bot.Handler(session, error)),
  timeout timeout: option.Option(Int),
  continue continue: fn(bot.Context(session, error), types.Video) -> Result(
    bot.Context(session, error),
    error,
  ),
) -> Result(bot.Context(session, error), error)

Pauses the current chat actor’s handler and waits for a video message. Other chats and users continue to be handled concurrently.

See conversation

wait_voice

</>

pub fn wait_voice(
  ctx ctx: bot.Context(session, error),
  or handle_else: option.Option(bot.Handler(session, error)),
  timeout timeout: option.Option(Int),
  continue continue: fn(bot.Context(session, error), types.Voice) -> Result(
    bot.Context(session, error),
    error,
  ),
) -> Result(bot.Context(session, error), error)

Pauses the current chat actor’s handler and waits for a voice message. Other chats and users continue to be handled concurrently.

See conversation

with_catch_handler

</>

pub fn with_catch_handler(
  builder: TelegaBuilder(session, error),
  catch_handler: fn(bot.Context(session, error), error) -> Result(
    Nil,
    error,
  ),
) -> TelegaBuilder(session, error)

Set catch handler for system errors (like session persistence failures) and conversation errors. This is different from router’s catch handler which handles route errors.

with_chat_config

</>

pub fn with_chat_config(
  builder: TelegaBuilder(session, error),
  restart_tolerance_intensity intensity: Int,
  restart_tolerance_period period: Int,
  init_timeout timeout: Int,
) -> TelegaBuilder(session, error)

Configure the chat instance factory supervisor.

restart_tolerance_intensity — max restarts within the period (default: 5)
restart_tolerance_period — period in seconds (default: 10)
init_timeout — chat instance init timeout in ms (default: 10 000)

with_nil_session

</>

pub fn with_nil_session(
  builder: TelegaBuilder(Nil, error),
) -> TelegaBuilder(Nil, error)

Set nil session for the bot.

with_polling_config

</>

pub fn with_polling_config(
  builder: TelegaBuilder(session, error),
  timeout timeout: Int,
  limit limit: Int,
  poll_interval poll_interval: Int,
) -> TelegaBuilder(session, error)

Set polling configuration for the supervised polling worker.

with_polling_on_stop

</>

pub fn with_polling_on_stop(
  builder: TelegaBuilder(session, error),
  on_stop on_stop: fn(error.TelegaError) -> Nil,
) -> TelegaBuilder(session, error)

Set a callback for when polling stops due to errors.

with_router

</>

pub fn with_router(
  builder: TelegaBuilder(session, error),
  router: router.Router(session, error),
) -> TelegaBuilder(session, error)

Set the router for handling updates. This is the primary way to handle updates - use router.new() to create a router and configure it with command handlers, text handlers, middleware, etc.

with_session_settings

</>

pub fn with_session_settings(
  builder: TelegaBuilder(session, error),
  session_settings: bot.SessionSettings(session, error),
) -> TelegaBuilder(session, error)

Set session settings for the bot.