telega

Types

pub opaque type Telega(session, error)
pub opaque type TelegaBuilder(session, error)

Values

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

Helper to get the config for API requests.

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

Get the bot’s information.

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

Get session for the current context.

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.

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

Initialize the bot.

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

Initialize the bot for long polling (doesn’t set webhook).

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.

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.

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.

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.

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

Context helpers for logging

pub fn new(
  token token: String,
  url server_url: String,
  webhook_path webhook_path: String,
  secret_token secret_token: option.Option(String),
) -> TelegaBuilder(a, b)

Create a new Telega instance.

pub fn new_for_polling(
  token token: String,
) -> TelegaBuilder(a, b)

Create a new Telega instance optimized for long polling.

This is a convenience function for polling bots that don’t need webhook configuration.

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

Set allowed updates for webhook.

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

Set a custom API client.

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

Set certificate for webhook.

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

Set whether to drop pending updates.

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

Set IP address for webhook.

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

Set max connections for webhook.

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)

Stops bot message handling from current chat and waits for any update.

See conversation

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)

Stops bot message handling from current chat and waits for an audio.

See conversation

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)

Stops bot message handling from current chat and waits for a callback query.

See conversation

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

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)

Stops bot message handling from current chat and waits for a specific command.

See conversation

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)

Stops bot message handling from current chat and waits for a specific command.

See conversation

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

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

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)

Stops bot message handling from current chat and waits for a message that matches the given Hears.

See conversation

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)

Stops bot message handling from current chat and waits for any message.

See conversation

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

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)

Stops bot message handling from current chat and waits for photos.

See conversation

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)

Stops bot message handling from current chat and waits for a text message.

See conversation

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)

Stops bot message handling from current chat and waits for a video.

See conversation

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)

Stops bot message handling from current chat and waits for a voice.

See conversation

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.

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

Set nil session for the bot.

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.

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

Set session settings for the bot.

Search Document