Packages

Multi-surface application runtime for Elixir. One TEA module renders to terminal, browser (LiveView), SSH, and MCP (agents). 30+ widgets, flexbox + CSS grid, distributed swarm with CRDTs, time-travel debugging, session recording, and an AST-checked REPL.

Current section

Files

Jump to
raxol docs features TELEGRAM.md
Raw

docs/features/TELEGRAM.md

# Telegram Surface

`raxol_telegram` runs a TEA app as a Telegram bot. Each chat gets a session with its own TEA model; inline keyboards become Button Components; HTML `<pre>` blocks render the buffer.

## Quick start

```elixir
# Add the supervisor with your TEA app module
children = [
  {Raxol.Telegram.Supervisor, app_module: MyApp.CounterApp}
]
```

Wire your Telegex polling/webhook handler into `Bot.handle_update/2`:

```elixir
defmodule MyApp.TelegramHandler do
  use Telegex.Polling.GenHandler

  @impl true
  def on_update(update) do
    Raxol.Telegram.Bot.handle_update(update, allowed_chat_ids: [123456789])
  end
end
```

The Telegex polling handler uses Telegex's own config (`config :telegex, token: ...`). The Bot API 10.x senders (`Raxol.Telegram.HTTP`) also take the token from a `bot_token:` option or `config :raxol_telegram, bot_token: ...`. `allowed_chat_ids` is passed at the `handle_update/2` call site.

Send a message to the bot from an allowed chat and the router spawns a `Session` for that chat. The session hosts a Lifecycle with `environment: :telegram`.

## Access control

`allowed_chat_ids` is optional. If set, the `Bot` update handler drops messages from other chats before they reach the router. Leave it out to accept all chats, not recommended unless the bot is public-facing.

## Session lifecycle

`SessionRouter` keeps a per-chat session map, capped at 1000 entries. New chats get a new session; existing chats route to the running one. Sessions idle out after 10 minutes of no traffic. A 5s cooldown between session creations rate-limits accidental floods.

| Event                  | What happens                                                              |
| ---------------------- | ------------------------------------------------------------------------- |
| Single-char text       | `:key` event with `char: <c>`                                             |
| Multi-char text        | `:paste` event with the trimmed text                                      |
| Inline `key:<name>`    | `:key` event (special key like `:up`/`:enter`, or char for length-1 keys) |
| Inline `btn:<id>`      | `:click` event with `component_id: <id>`                                  |
| `/start`               | Session created (or routed to existing one)                               |
| `/stop`                | Session terminated                                                        |
| 10min silence          | Session terminates, model dropped                                         |

## Output

`OutputAdapter` takes the screen buffer and produces a Telegram message:

- Buffer -> HTML `<pre>` block (with monospace styling preserved)
- Interactive Components -> inline keyboard buttons in document order

Message edit dedup prevents redundant API calls when the rendered output doesn't change between updates.

## Security

`telegex` is an optional dep. Without it the surface compiles but does nothing, useful for environments where Telegram isn't wanted.

The bot token is the only secret. Don't commit it; load via `System.fetch_env!/1` at runtime.

## Bot API 10.x surface (2026-06)

Telegram's June 2026 release added rich-text messages, admin bots for `chat_join_request` updates, and poll hyperlinks. `raxol_telegram` 0.2 covers all three plus an MCP export path for the Guardian decisions.

These features ride on top of the per-chat Session model above. They use `Raxol.Telegram.HTTP` (shared raw `Req` transport with `post_fn` injection for tests) because Telegex 1.8 predates Bot API 10.1 and does not expose the new endpoints. The package adds `req ~> 0.5` as an optional dep; without it, the HTTP-bound modules return `{:error, :req_not_available}` and consumers can call `to_payload/3` themselves to get the JSON body.

### Rich messages (`Raxol.Telegram.RichMessage`)

Builders for Bot API 10.1's `sendRichMessage` family. Paragraph, heading (1-6), table + cell, list + list_item (ordered / unordered), details (collapsible "Show More"), math (block + inline), thinking. Inline formatting: bold, italic, underline, strikethrough, code, spoiler, subscript, superscript.

```elixir
import Raxol.Telegram.RichMessage

msg = rich_message([
  heading(1, "Build status"),
  paragraph([bold("master"), text(" is red")]),
  details([text("Show stacktrace")], [paragraph([code("UndefinedFunctionError")])]),
  table([
    [cell([bold("Module")]), cell([bold("Coverage")])],
    [cell([text("Bot")]),    cell([text("94%")])]
  ]),
  math(~S"\\int_0^1 x^2 dx = \\frac{1}{3}")
])

{:ok, _} = Raxol.Telegram.RichMessage.Sender.send(chat_id, msg)
```

`chunk/2` enforces the 32K hard cap (returns `{:error, :too_long}` rather than truncating) and the 8K Show More boundary (wraps the tail of long content in a `details` block). Sender telemetry: `[:raxol_telegram, :rich_message, :sent | :error]` with `chat_id`, `byte_size`, `chunked?`, `reason`.

### AI Guardian ([ADR-0014](https://github.com/DROOdotFOO/raxol/blob/master/docs/adr/0014-telegram-ai-guardian.md))

Behaviour for screening `chat_join_request` updates. Guardian runs outside the per-chat Session model: applicants are keyed by user, not chat, and the decision (approve / decline / hand off to a mini-app) happens at the Bot dispatch layer.

```elixir
defmodule MyApp.SpamFilter do
  @behaviour Raxol.Telegram.Guardian

  @impl true
  def screen(applicant) do
    cond do
      blocked?(applicant.user_id) -> {:decline, "user previously banned"}
      missing_bio?(applicant)     -> {:ask_mini_app, "https://verify.myapp.com", "Verify"}
      true                        -> {:approve, nil}
    end
  end
end

# In app env:
config :raxol_telegram, guardian: MyApp.SpamFilter
```

`Bot.handle_update/2` gains a new clause for `%{chat_join_request: _}`. The applicant payload is normalised by `InputAdapter.translate_join_request/1` (handles both atom-keyed and string-keyed maps). `Guardian.decide/2` invokes the configured module's `screen/1`; `Guardian.apply_decision/3` calls the Bot API.

Bot API path selection is automatic: when the applicant carries a `query_id` (Bot API 10.1+), `apply_decision/3` uses `answerChatJoinRequestQuery`; without `query_id`, it falls back to the pre-10.0 `approveChatJoinRequest` / `declineChatJoinRequest` pair. The 10.1 path auto-falls back on `bot_api_error` too (e.g. against an older API server).

For the `:ask_mini_app` path, `Raxol.Telegram.MiniApp.build_url/2` appends `chat_id`, `user_id`, and `query_id` as query parameters so the consumer-hosted mini-app backend has everything it needs to call `answerChatJoinRequestQuery` itself with the right context. The mini-app is not hosted by `raxol_telegram`.

Guardian telemetry: `[:raxol_telegram, :guardian, :received | :approved | :declined | :asked | :denied | :error]`. All carry `chat_id` and `user_id`; terminal events also carry `reason` (or `url` for `:asked`), `source` (`:bot` or `:mcp`), and `error_reason` for failures.

### MCP Exports

`Raxol.Telegram.Guardian.MCPTools.register/0` exposes four tools through `Raxol.MCP.Registry`. Symmetric with [ADR-0012](https://github.com/DROOdotFOO/raxol/blob/master/docs/adr/0012-mcp-as-rendering-target.md): an external agent can observe and override Guardian decisions over MCP without protocol glue.

| Tool | Purpose |
|------|---------|
| `telegram_guardian_approve` | Admit an applicant (10.1 or pre-10.0 path, same selection logic) |
| `telegram_guardian_decline` | Reject an applicant |
| `telegram_guardian_screen`  | Run the configured screener on a synthetic applicant without applying the decision |
| `telegram_guardian_list_pending` | Returns `[]` in v1; persistence lands in v2 |

Registration is opt-in and requires `raxol_mcp` at runtime; without it, `register/0` returns `{:error, :raxol_mcp_not_available}` and the rest of the package keeps working. No compile-time dep on `raxol_mcp`.

### Polls with hyperlinks (`Raxol.Telegram.Poll`)

`send_poll/4` accepts options as plain `String.t()`, `{:link, label, url}` tuples (entire text is one hyperlink), or `%{text: ..., entities: [...]}` maps for arbitrary entity layouts. `link_entity/3` builds a `text_link` entity at a specific UTF-16 offset.

```elixir
import Raxol.Telegram.Poll

send_poll(chat_id, "Which doc?",
  [
    "Plain text option",
    link_option("Read ADR-0014", "https://github.com/example/adr/0014"),
    %{text: "See source", entities: [link_entity(4, 6, "https://github.com/example")]}
  ],
  is_anonymous: false,
  allows_multiple_answers: true,
  bot_token: token
)
```

Option count is validated client-side (2-10); other constraints (text length, entity bounds) are left to the API.

### Self-hosted bot API server

For groups expecting >30 req/s during join floods (Telegram's public API rate cap), point `:api_base` at a [gramiojs/telegram-bot-api](https://github.com/gramiojs/telegram-bot-api) Docker image:

```elixir
Raxol.Telegram.RichMessage.Sender.send(chat_id, msg,
  bot_token: token,
  api_base: "https://bot-api.internal"
)
```

The same `:api_base` option works on `Raxol.Telegram.Poll.send_poll/4` and `Raxol.Telegram.Guardian.apply_decision/3` (shared `HTTP` transport).

## As a gateway adapter

`Raxol.Telegram.GatewayAdapter` puts Telegram behind the frozen
`Raxol.Gateway.Adapter` contract (requires the optional `raxol_gateway`
dependency; it compiles only when `raxol_gateway` is already compiled, so after
adding `raxol_gateway` to a project that has `raxol_telegram`, run
`mix deps.compile raxol_telegram --force`): text messages normalize to the gateway's `%{text: binary}` event
shape, replies go out as plain-text `sendMessage` calls chunked at Telegram's
4096 UTF-16-code-unit limit. `Raxol.Telegram.UpdatePoller` is the matching
update feed: a supervised `getUpdates` long-poll loop with exponential backoff
and a sink-agnostic `:on_update` function, so it drives either the gateway
router or `Bot.handle_update/2`. Callbacks, keyboards, and media stay on the
TEA surface (this package's `Session`); the gateway path is text-first. See
[Gateway](GATEWAY.md) for the full wiring example.

## See also

- [Gateway](GATEWAY.md): multi-platform gateway; Telegram is the first adapter behind the frozen contract
- [Watch](WATCH.md): another push surface for mobile
- [Agent Framework](https://github.com/DROOdotFOO/raxol/blob/master/docs/features/AGENT_FRAMEWORK.md): if your bot is an agent, use this stack
- [ADR-0014](https://github.com/DROOdotFOO/raxol/blob/master/docs/adr/0014-telegram-ai-guardian.md): full Guardian design rationale