Build a Context for work happening outside an update: a background job that finished, a cron tick, a webhook from another service.

The context carries the same config, injected dependencies and bot info a handler would see, and the user’s persisted session — so a render or a reply.* call behaves as it does inside an update.

Two things it cannot carry, because there is no chat instance behind it:

• ctx.update is a placeholder holding only chat_id/from_id (an UnknownUpdate). Anything reading the update’s content sees nothing.
• wait_* and cancel_conversation_in have no instance to suspend, so they do nothing. Start conversations from a real update.

Fails when the session cannot be read — same rule as a chat instance start: acting on a default here would persist it over the real session.

// Refresh a user's open dialog once their export finishes.
let assert Ok(ctx) = telega.background_context(bot, chat_id:, user_id:)
let _ = dialog.refresh(ctx, registry, dialog_id: "export")

Cancel the conversation a chat is currently waiting in.

key is the session key of the chat instance — the "{chat_id}:{from_id}" string available in any handler as ctx.key. The pending wait_* continuation is dropped, so the next update from that chat is routed normally again. The chat instance itself and its session are untouched, and cancelling a chat that is not waiting for anything does nothing.

Compare two secrets without giving away where they first differ.

== on binaries stops at the first differing byte, so the response time reveals how long a shared prefix is and the secret can be guessed one byte at a time. Use this in your own webhook adapter for any value an attacker gets to retry.

Read the dead-letter queue without touching it.

Error when the bot has no queue configured or the backend could not be read; the second element of the pair lists entries that would not decode.

Default time (ms) health waits for the bot actor to answer.

Inject typed, non-persisted dependencies (services) available in every handler via ctx.dependencies (or get_dependencies).

Use this for things that are not user state and must not be persisted — a database pool, an http client, an i18n catalog, configuration. The rule of thumb: session is the user’s state (persisted), dependencies is the bot’s services (set once at startup, never persisted).

Only callable while the builder is Fresh, i.e. before router or any other handler that is typed against dependencies. Calling it later is a compile error rather than a silently dropped router.

telega.new(api_client)
|> telega.dependencies(Dependencies(db:, catalog:))
|> telega.router(router)
|> telega.start()

Forget one dead letter by its storage key, without replaying it.

Helper to get the config for API requests.

Get the injected dependencies (services) for the current context.

dependencies is set once at bot init via with_dependencies and is never persisted. See the session vs dependencies distinction in with_dependencies.

Get the bot’s information.

Get session for the current context.

Get the supervisor PID for the running bot instance.

Handle an update.

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

Handle an update, allowing the handler to answer it directly in the webhook HTTP response body (webhook reply).

Waits up to timeout ms for the handler to either claim an eligible API call (see telega/webhook_reply) or finish. On a claim it returns JsonResponse for the adapter to send back; otherwise EmptyResponse. After the timeout the handler keeps running in the background and all its API calls go over regular HTTP.

Pick a timeout safely below Telegram’s webhook timeout — e.g. 5000 ms. Adapters expose this as handle_bot_with_reply; use this function directly only when implementing your own adapter.

⚠️ A claimed call resolves to a synthetic stub in the handler: True for boolean methods, a fake Message (message_id: -1, date: 0) for sendMessage. Full guide in the telega/webhook_reply module docs.

Ask the running bot how it is doing.

The answer comes from the bot actor’s own mailbox, so an actor that has died or wedged reports Unavailable rather than a stale snapshot — which is exactly what a load balancer needs to know.

case telega.health(bot) {
  telega.Healthy(..) -> wisp.ok()
  _ -> wisp.response(503)
}

The webhook adapters (telega_wisp.handle_health, telega_mist.handle_health) wrap this into a ready-made /healthz endpoint.

The HTTP status a health endpoint should answer with: 200 when healthy, 503 otherwise.

A JSON body for a health endpoint: {"status":"healthy","in_flight":3,"chat_instances":41}.

status is one of healthy, draining, overloaded, unavailable.

Like health, with an explicit timeout (ms) for the actor’s reply.

Whether the bot is currently draining and no longer accepting updates.

Webhook adapters should answer 503 when this is True so Telegram retries the update after the deploy instead of it being dropped.

Whether the bot is ready to take another update.

Check if a secret token is valid.

Useful if you plan to implement own adapter.

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

Useful if you plan to implement own adapter.

Run fun with a logging context: every log line it writes is prefixed with prefix and carries the update’s identifiers as structured logger metadata.

The metadata fields are telega_prefix, chat_id, from_id, update_id and session_key. They are set as Erlang logger process metadata, so they reach any handler or formatter that reads it — including log lines written by libraries that know nothing about telega:

%% sys.config
{kernel, [{logger, [{handler, default, logger_std_h,
  #{formatter => {logger_formatter,
    #{template => [time," ",level," chat=",chat_id," upd=",update_id," ",msg,"\n"],
      single_line => true}}}}]}]}

The previous metadata is restored when fun returns, so nested contexts stack and unwind.

use ctx <- telega.log_context(ctx, "checkout")
telega.log_info(ctx, "starting")
reply.text(ctx, "One moment…")

Context helpers for logging

Start building a bot from an API client.

The client comes from an adapter package like telega_httpc or telega_hackney. The builder starts out in long-polling mode with a Nil session and no injected dependencies; polling, webhook, session and dependencies change that.

telega.new(api_client)
|> telega.dependencies(Dependencies(db:, catalog:))
|> telega.session(session_settings)
|> telega.router(router)
|> telega.start()

dependencies and session fix type parameters the router is typed against, so they only compile before router (see Fresh).

Receive updates by long polling (the default) with explicit settings.

telega.new(api_client)
|> telega.router(router)
|> telega.polling(polling.PollingSettings(
  ..polling.default_settings(),
  limit: 10,
))
|> telega.start()

A builder that calls neither polling nor webhook polls with polling.default_settings().

Feed every stored dead letter back through the bot, dropping each entry the bot handles.

Run it once the bug that crashed the handler is fixed — a replayed update that crashes again is dead-lettered afresh under the same key, so the queue does not grow. Updates are replayed oldest update_id first, one at a time, and each is dispatched exactly like an update arriving from Telegram (the same routing, the same session, the same pre-router middleware). An update the bot declines (False) keeps its entry.

This is deliberately a manual operation: replaying a queue full of updates the users have long since moved past is rarely what you want automatically.

Set the router that handles updates.

This is the primary way to handle updates — build one with router.new() and register commands, text handlers, middleware on it. For a composition built with router.compose/router.branch, use router_tree.

Set a composed router.RouterTree that handles updates.

let tree =
  router.tree()
  |> router.branch(router.is_private_chat(), private_router)
  |> router.branch(router.is_group_chat(), group_router)

telega.new(api_client)
|> telega.router_tree(tree)

Give the bot a persisted session.

Without this call the bot runs on the stateless Nil session — there is no separate “nil session” constructor to remember. Storage adapters build the settings for you (storage.session_settings_from_storage and friends).

Like dependencies, it fixes a type parameter the router is typed against, so it only compiles while the builder is Fresh.

telega.new(api_client)
|> telega.session(storage.session_settings_from_storage(
  storage:,
  encode: encode_session,
  decode: session_decoder(),
  default: fn() { Session(count: 0) },
))
|> telega.router(router)
|> telega.start()

Graceful shutdown with in-flight draining.

1. Emits [telega, shutdown, start].
2. Stops intake — for polling, tells the worker to stop fetching updates (Telegram re-delivers unconfirmed updates on the next start); for webhook, the bot starts rejecting updates and is_draining reports True so adapters can answer 503.
3. Waits up to drain_timeout for in-flight updates to finish.
4. Runs the on_shutdown hook.
5. Emits [telega, shutdown, stop] with the number of drained updates.
6. Stops the supervisor, cascading to all children (polling → bot → chat_factory).

Start the bot.

Builds the supervision tree (chat instance factory → bot, plus a polling worker in polling mode) and, in webhook mode, registers the webhook with Telegram. Fails when the router is missing, the token is rejected, or a child cannot start.

let assert Ok(bot) =
  telega.new(api_client)
  |> telega.router(router)
  |> telega.start()

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

Run the bot as a child of your own supervision tree.

Wraps start into a ChildSpecification: telega still builds and owns its internal chat factory → bot (→ polling) tree, but that tree’s root becomes a child of YOUR supervisor. If the bot tree dies, your supervisor restarts it by re-running start — setWebhook (webhook mode), getMe and a fresh internal tree.

Add it after the resources the bot depends on (database pool, caches) — with a RestForOne strategy a dead dependency restarts the bot too:

let bot_ready = process.new_subject()
let bot_child =
  telega.new(api_client)
  |> telega.webhook(url:, path:, secret_token:)
  |> telega.router(router)
  |> telega.with_on_start(fn(bot) { Ok(process.send(bot_ready, bot)) })
  |> telega.supervised()

let assert Ok(_) =
  static_supervisor.new(static_supervisor.RestForOne)
  |> static_supervisor.add(db_pool_child)
  |> static_supervisor.add(bot_child)
  |> static_supervisor.start

// Webhook adapters need the instance — receive it from the hook.
let assert Ok(bot) = process.receive(bot_ready, within: 10_000)

The started Telega instance is the child’s data; supervisors don’t hand child data back, so capture it in with_on_start as above when you need it outside the tree (webhook adapters, manual shutdown). Stopping your tree stops the bot the standard OTP way (no drain); for a drained stop use shutdown or with_signal_handlers.

Register a global pre-router middleware (bot.PreHandler).

Pre-router middleware runs once per update inside the bot actor, before routing and before any chat instance is spawned or session loaded. Use it for cross-cutting concerns that apply to every update: anti-spam, analytics, and update deduplication. Returning bot.Stop drops the update before routing; bot.Continue lets it through to the next pre-handler and the router. Handlers run in the order they are registered, and the first Stop short-circuits the rest. Because they all run sequentially in the single bot actor, read-then-write logic (like dedup) is race-free across updates.

// Drop updates from a banned chat before they reach any handler.
telega.new(api_client)
|> telega.use_pre_handler(fn(pre) {
  case pre.update.chat_id == banned_chat {
    True -> bot.Stop
    False -> bot.proceed()
  }
})
|> telega.router(router)

// Webhook idempotency: drop updates Telegram re-delivers on retry.
|> telega.use_pre_handler(idempotency.deduplicate(storage:, ttl_ms: 3600_000))

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

See conversation

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

See conversation

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 for user choice from inline keyboard.

This function sends text with an inline keyboard built from options and waits for user to select one.

If the prompt cannot be sent (network error, bot blocked, empty text), the error is logged and the conversation is not started: the function returns Ok(ctx) instead of waiting for a press that can never come.

Examples

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

See conversation

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

See conversation

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 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

Pauses the current chat actor’s handler and waits for an update that matches a composable router.Filter.

Unlike the typed waiters (wait_text, wait_photos, …) which each listen for a single update type, this accepts the router’s filter combinators, so a single continuation can wait for several types at once. Combine with router.or/router.or2 (any), router.and/router.and2 (all) and router.not:

use ctx, upd <- wait_filtered(
  ctx,
  filter: router.or2(router.is_text(), router.has_photo()),
  or: None,
  timeout: None,
)
case upd {
  update.TextUpdate(text:, ..) -> // ...
  update.PhotoUpdate(photos:, ..) -> // ...
  _ -> // ...
}

wait_for remains the escape hatch for a raw fn(Update) -> Bool predicate.

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

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

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

See conversation

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

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

See conversation

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

See conversation

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

See conversation

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

See conversation

Receive updates through a webhook, registered with setWebhook on start.

url is the public base URL of your server and path the route your web adapter serves; Telegram is told to POST to url <> "/" <> path. A secret_token of None generates a random one — adapters compare it for you (is_secret_token_valid).

telega.new(api_client)
|> telega.webhook(
  url: "https://bot.example.com",
  path: "webhook",
  secret_token: Some(secret),
)
|> telega.router(router)
|> telega.start()

Restrict the update types Telegram sends, by hand.

Always wins over with_auto_allowed_updates — this is the escape hatch for when derivation is not what you want. A name this Bot API version does not have is kept (Telegram is the authority) but logged, since the usual reason for one is a typo that quietly costs the bot an update kind.

Derive allowed_updates from the router’s registered routes.

Telegram then sends only the update types the bot actually handles, cutting out traffic for routes you never registered. A manual with_allowed_updates always wins (the escape hatch). If the router has a fallback, custom, or filtered route — which can match anything — derivation can’t narrow safely and falls back to Telegram’s default update set.

Publish the router’s commands to Telegram on start.

Every command registered with router.on_command_with_description is sent via setMyCommands once the bot is up, so the Telegram client shows them in the command menu without a manual call. Commands added with plain router.on_command (no description) are not published.

For localized descriptions use with_command_translations instead — it turns this on as well.

telega.new(api_client)
|> telega.router(router)
|> telega.with_auto_commands()
|> telega.start()

Set the catch handler for system errors (like session persistence failures) and conversation errors.

This is different from the router’s catch handler, which handles route errors.

Upload a self-signed certificate along with the webhook.

Compact a chat instance’s heap once it has been quiet for after milliseconds (default: bot.default_hibernate_after, one minute).

An instance that handled a burst of messages keeps the heap that burst grew until it is evicted. One full garbage collection after the chat goes quiet gives it back, which for a bot holding many idle instances is the difference between kilobytes and tens of kilobytes each.

Stop chat instances that have been idle for timeout milliseconds.

One ChatInstance process is started per {chat_id}:{from_id}, so a bot used by many distinct people accumulates one process (plus its session and any suspended conversation) per person. They are evicted after half an hour of silence by default — bot.default_chat_idle_timeout — and this changes that bound.

An instance that has received nothing for that long is deregistered and stopped by the bot actor. The next update from that user simply starts a fresh instance, which re-reads the session from storage — so nothing persisted is lost.

A pending conversation (wait_*) lives only in the instance’s memory, so it is dropped along with the instance. Pick an idle timeout comfortably larger than the conversation timeouts you use.

telega.new(api_client)
|> telega.router(router)
// reclaim a user's process after five minutes of silence
|> telega.with_chat_idle_timeout(1000 * 60 * 5)
|> telega.start()

Set how long (ms) a chat instance may take to start, which includes loading its session from storage (default: 10 000).

Set how tolerant the chat instance factory supervisor is of restarts: at most intensity restarts within period seconds (default: 5 in 10).

Publish localized command descriptions on start.

Implies with_auto_commands: the default-language commands are published first, then for every locale in locales a setMyCommands(language_code:) call is made. translate(command, locale) supplies the per-language text; returning None keeps the router’s default description for that command.

telega_i18n provides a convenience wrapper that builds translate from a translation catalog, so you usually call this through it.

telega.new(api_client)
|> telega.router(router)
|> telega.with_command_translations(
  locales: ["en", "ru"],
  translate: fn(command, locale) { lookup_description(command, locale) },
)
|> telega.start()

Keep updates whose chat instance crashed, so a panic costs a log line and a stored update instead of the update itself.

See telega/dead_letter for what is stored and replay_dead_letters for feeding them back in.

telega.new(api_client)
|> telega.router(router)
|> telega.with_dead_letters(storage.dead_letters_from_storage(
  storage,
  retention_ms: Some(7 * 24 * 60 * 60 * 1000),
))
|> telega.start()

Set the maximum time (in milliseconds) shutdown waits for in-flight updates to finish before forcibly stopping the supervision tree.

Defaults to 5000ms.

Drop the updates Telegram accumulated while the bot was down (webhook mode).

Add update types to the auto-derived allowed_updates.

Derivation only sees the router. Updates a conversation or a flow waits for are invisible to it: a bot whose router registers only commands, but whose handlers use wait_callback, derives ["message"] — and then waits forever for a callback_query Telegram was never asked to send.

|> telega.with_auto_allowed_updates()
|> telega.with_extra_allowed_updates(["message_reaction"])

Has no effect when derivation already returns “do not restrict” (a router with a fallback, custom or filtered route), and none when with_allowed_updates set the list manually.

Set the fixed IP address Telegram sends webhook updates to.

Set the maximum number of simultaneous webhook connections Telegram opens.

Cap how much work the bot admits to before it reports itself overloaded.

The bot actor counts updates currently being handled by chat instances. Once that count reaches limit, health answers Overloaded and the webhook adapters (telega_wisp, telega_mist) answer 503 — so Telegram backs off and redelivers instead of piling more work onto a bot that is already behind. Long polling needs no such cap: its worker already stops fetching while limit updates are in flight.

Pick it from what the bot can actually keep up with; there is no useful default, so without this call overload is never reported.

telega.new(api_client)
|> telega.router(router)
|> telega.webhook(url:, path:, secret_token:)
|> telega.with_max_in_flight(500)
|> telega.start()

Gather the messages of an album into a single MediaGroupUpdate.

Telegram delivers an album as separate messages that share a media_group_id, so without this setting they arrive one by one on on_photo / on_video / on_audio and router.on_media_group never fires. With it, a chat instance holds them back until timeout milliseconds pass without another message of the same album (1000 is a good starting point) and then routes them together.

The individual messages are not delivered as well — a bot that turns this on handles albums in on_media_group and single media in on_photo and friends. Messages that arrive while a wait_* conversation is pending are left alone, since the waiting handler expects them one at a time.

telega.new(api_client)
|> telega.router(router)
|> telega.with_media_group_timeout(1000)
|> telega.start()

Set a hook to run during shutdown, after in-flight updates have drained and before the supervision tree is stopped. Use it to release resources (close pools, flush buffers, deregister from a service discovery, …).

Set a hook to run once the bot has fully started.

Runs after the supervision tree is up and the Telega instance is built, so you can use it for warming caches, registering commands via the API, etc. Returning Error aborts startup and tears the supervision tree back down.

telega.new(api_client)
|> telega.router(router)
|> telega.with_on_start(fn(bot) {
  // register commands, warm caches...
  Ok(Nil)
})
|> telega.start()

Choose what an update is keyed by — its session and the chat instance that handles it.

The default is bot.default_session_key: "{chat_id}:{from_id}", one session per user per chat. bot.chat_session_key gives a group one shared session (and one instance, so members are serialized through it); bot.user_session_key follows a user across chats. Anything else is a function of the update:

// One session per forum topic rather than per chat.
telega.with_session_key(builder, fn(update) {
  case update.thread_id {
    Some(thread) -> int.to_string(update.chat_id) <> ":t" <> int.to_string(thread)
    None -> bot.default_session_key(update)
  }
})

Two updates that map to the same key share one process and one session, so the key decides both concurrency and isolation. The trade-offs of the built-in keys — anonymous group admins, inline-message callbacks, updates with no user — are in docs/session-serialization.md.

Choose what happens when the session cannot be read from storage.

The default is bot.FailUpdate: the chat instance refuses to start and the update is reported unhandled, because serving it on a default session would let the first handler persist that default over the real, still-stored data. bot.ReadOnly keeps the bot answering while the backend is down (handlers run on the default session, every write is skipped with a warning); bot.UseDefault is the old, lossy behaviour — pick it only when losing a session costs less than dropping the update.

telega.new(api_client)
|> telega.session(settings)
|> telega.with_session_load_error(bot.ReadOnly)

Choose whether a session no handler changed is still written back.

The default is bot.PersistOnChange: a handler that returns the session it was given costs no storage write at all, which for a bot whose handlers mostly read is most of its writes. Switch to bot.PersistAlways when the write itself does something you rely on — refreshing an expiry, touching a “last seen” column.

telega.new(api_client)
|> telega.session(settings)
|> telega.with_session_persistence(bot.PersistAlways)

Install an OS signal handler (SIGTERM) that runs a graceful shutdown and then halts the VM.

This makes the bot survive rolling deploys on platforms like fly.io or Kubernetes: on SIGTERM the bot stops accepting new updates, drains in-flight work (bounded by with_drain_timeout), runs the on_shutdown hook, and stops cleanly. The handler replaces the runtime’s default signal behavior.

Only SIGTERM is handled — BEAM reserves SIGINT for its interactive break handler, so it cannot be intercepted this way.

Never compact an idle chat instance’s heap.

Keep every chat instance alive for as long as the bot runs.

This undoes the default half-hour eviction. Only worth it when a bot serves a small, known set of chats and wants their in-memory conversations to survive any amount of silence — an open-ended process per user is exactly how a busy bot runs out of BEAM processes.