Telegram Bot Provider¶

Acteon ships with a first-class Telegram Bot provider that sends messages via the Telegram Bot API's sendMessage endpoint. Operators use it for any workflow that maps to an Acteon Action — on-call alerting, deployment notifications, approval callbacks inside chains, scheduled reminders, and anything else that fits the single-shot "post to a chat" shape of the Telegram Bot API.

Like the other native providers, acteon-telegram:

• Holds the bot token as SecretString, zeroized on drop. The token is percent-encoded in the URL path so the {bot_id}:{auth} colon separator cannot collapse the route.
• Supports multiple chats per provider instance so one config can fan messages out to several groups, users, or channels.
• Maps 5xx / 408 → retryable Connection (via a Transient variant); 429 → retryable RateLimited; 401/403/404 → non-retryable Configuration (404 on /bot{token}/... means an unrecognized token — operator error, not transient); other 4xx → non-retryable ExecutionFailed.
• Handles Telegram's 200 OK + ok: false edge case by classifying it as a permanent ExecutionFailed.
• Reuses the server's shared HTTP client, so it participates in circuit breaking, provider health checks, and per-provider metrics automatically.
• Verifies credentials in the health check: unlike most provider APIs, Telegram ships a free, idempotent getMe endpoint explicitly designed as a credential-validity probe. The Telegram provider parses the response and surfaces bad tokens as non-retryable Configuration errors — operators see token problems on the health dashboard instead of only at dispatch time.
• Propagates W3C Trace Context headers.

TOML configuration¶

[[providers]]
name = "telegram-ops"
type = "telegram"
telegram.bot_token = "ENC[AES256_GCM,data:abc123...]"
telegram.default_chat = "ops-channel"
telegram.default_parse_mode = "HTML"         # optional
# telegram.text_max_utf16_units = 4096        # default — matches the Bot API's UTF-16 unit cap

[providers.telegram.chats]
ops-channel  = "-1001234567890"
dev-channel  = "@devchannel"
alice-direct = "123456789"

Why UTF-16 code units (not bytes)¶

The Telegram Bot API expresses the 4096-character text limit in UTF-16 code units, not UTF-8 bytes. One BMP character (Latin, Cyrillic, Hebrew, Arabic, most CJK) costs 1 code unit; one non-BMP character (most emoji at U+1F000 and above, supplementary CJK ideographs) costs 2 code units (a surrogate pair).

Counting in UTF-16 units matches the API exactly. The earlier revision of this provider counted bytes instead, which meant CJK traffic truncated at ~1365 characters (because CJK is 3 bytes per character in UTF-8) even though the API would have accepted the full 4096-character message. The current implementation gives CJK and emoji-heavy deployments the full runway the API actually permits.

Payload shape¶

Telegram has no lifecycle concept — the provider accepts one event_action, "send" (also the default when omitted). Only text is required.

{
  "text": "Deploy #4823 completed successfully.",
  "chat": "ops-channel"
}

HTML-formatted alert to a forum-group topic¶

{
  "text": "<b>CRITICAL</b>: checkout-api error rate above SLO.\n<i>Investigate immediately.</i>",
  "chat": "ops-channel",
  "parse_mode": "HTML",
  "disable_web_page_preview": true,
  "protect_content": true,
  "message_thread_id": 7
}

Rule integration¶

Because Telegram is just another named provider, every routing primitive Acteon already has works with it:

• Reroute critical alerts to a Telegram channel by matching on action.payload.severity == "critical" with a reroute rule.
• Silence maintenance windows with silences — silences apply before the provider dispatch.
• Quota-bound a Telegram bot with a per-provider tenant quota scoped to provider: "telegram-ops" — Telegram's own per-bot limits are 30 messages/second globally and 20 messages/minute per group, so a quota is useful defense-in-depth.
• Dedup noisy events with Acteon's deduplication using Action.dedup_key.

Outcome body¶

On success the provider returns an Executed outcome whose body carries the Telegram response:

{
  "ok": true,
  "message_id": 42
}

The message_id is the Telegram server's assignment for the delivered message — useful in chains where a later step needs to edit or reply to an earlier Telegram post.

Error mapping¶

Why 404 → Configuration: the Telegram Bot API routes every call through /bot{token}/.... A 404 on that path means the server did not recognize the token — which is an operator problem, not a transient one. The same class of response on the other provider crates would be 401, but Telegram sometimes uses 404 here.

Simulation example¶

A full demo — plain-text notification, HTML alert to a forum-group topic, and a rule-based reroute — is in crates/simulation/examples/telegram_simulation.rs:

cargo run -p acteon-simulation --example telegram_simulation

The simulation uses a recording provider, so it runs offline with no real Telegram credentials.