Telegram

PublishedDocs / Augments

Run text turns through a Telegram bot with polling or webhooks and static operator-configured identity lists.

What it enables

A Telegram text message becomes an Auggy turn, and the agent sends its text reply back to the same Telegram chat.

Status: Stable
Availability: Install with `auggy augment add telegramTransport`. Configure a Telegram bot token and one inbound mode.

Contributes

transporttext inboundtext outbound

Identity is resolved from static Telegram user-ID configuration. This transport does not dynamically integrate with `visitorAuth`; configure creator, admitted-agent, and recognized-user IDs directly.

Install and configure

1Create a bot with @BotFather and put its token in `.env`.
2Find the operator's numeric Telegram user ID, set `TELEGRAM_CREATOR_USER_IDS`, and send the bot a first message.
3Run `auggy augment add telegramTransport`. The default is polling; use webhook mode only with a public HTTPS endpoint.

.env.env

TELEGRAM_BOT_TOKEN=replace-with-botfather-token
TELEGRAM_CREATOR_USER_IDS=123456789

augments/telegramTransport/augment.yamlyaml

type: telegramTransport
config:
  botToken: ${TELEGRAM_BOT_TOKEN}
  inbound:
    mode: polling
    polling:
      timeoutSec: 30
  auth:
    creatorUserIds: []
    creatorUserIdsEnv: TELEGRAM_CREATOR_USER_IDS
    anonymousIdentityMode: ephemeral

Webhook production variantyaml

type: telegramTransport
config:
  botToken: ${TELEGRAM_BOT_TOKEN}
  inbound:
    mode: webhook
    webhook:
      publicUrl: https://agent.example.com/telegram
      port: 8081
      secretToken: ${TELEGRAM_WEBHOOK_SECRET}
      allowedUpdates:
        - message
  auth:
    creatorUserIds: []
    creatorUserIdsEnv: TELEGRAM_CREATOR_USER_IDS
    anonymousIdentityMode: ephemeral

Use a Telegram operations bot

A creator can use a private Telegram chat to check a deployment without opening the web console. The creator ID is resolved before the turn, so creator-only tools and policies remain available.

Telegram DM to the bottext

Check the latest deployment status, report any failed health checks, and do not change production.

The inbound thread is `tg-chat-<chatId>`. The reply is sent with Telegram `sendMessage` to the chat that produced the turn.

Runtime surfaces

Surface	Current behavior	Exact shape
Polling ingress	Long-polls Telegram and dispatches text updates.	`getUpdates` with `inbound.polling.timeoutSec` (default 30)
Webhook ingress	Runs a Bun HTTP server and accepts authenticated Telegram POST updates.	`POST` on `inbound.webhook.port` (default 8081)
Kernel handoff	Creates a message trigger and calls the shared kernel turn path.	`transport.register` + `kernel.handleInbound`
Reply egress	Concatenates text parts and replies to the originating chat.	Telegram Bot API `sendMessage`
Thread identity	Maps one Telegram chat to one Auggy thread.	`tg-chat-<chatId>`

Boundaries

Boundary	Current behavior
Trust	Private-chat user IDs in `creatorUserIds` resolve to creator. `admittedAgents` resolve to agent, `recognizedUserIds` to recognized public, and all other users to anonymous public. Group messages are not promoted to creator by the creator ID alone. A failed admitted-agent boot health check logs a warning but does not remove that configured agent mapping.
Persistence	Thread history, memory, and budgets use Auggy's configured stores. Anonymous IDs are ephemeral by default (`tg_anon_<threadId>`); `durable` uses `tg_user_<userId>` across chats. Telegram polling offset and the thread-to-chat reply map are process-local.
Deployment	Polling needs no public HTTPS endpoint and works with the generated Railway service. Webhooks need a publicly reachable HTTPS URL, forwarded `X-Telegram-Bot-Api-Secret-Token`, and one active mode per bot. The generated Railway deployment exposes only Web Transport on port 8080, so webhook mode on its separate port requires custom ingress or external routing.
Transport	Inbound and reply messages are text-only. There is no streaming edit, media, attachment, or file-message handling in this transport. Use `notify` for proactive Telegram messages to configured destinations.
Auth model	Auth lists are static config and environment-backed numeric IDs. There is no dynamic `visitorAuth` handoff or app-login bridge in this augment.

Verify

1Start the agent with `auggy run` and confirm Telegram is running in the Console integration details.
2Send a text DM to the bot and confirm one turn is recorded with the expected `tg-chat-<chatId>` thread.
3Confirm the text reply arrives in the same chat. If the turn fails, verify that the user-safe failure text does not expose provider credentials.
4For webhook mode, send a POST with the configured secret header and inspect Telegram `getWebhookInfo` if updates do not arrive.
5Check the identity path with a creator, admitted agent, recognized user, and unknown user before enabling sensitive tools.

Add an augmentInstall layeredMemory, inspect what the CLI adds, and verify peer-scoped memory in Console.Web TransportServe AG-UI turns, the operator Console, health checks, and runtime discovery.Turn ControlEnd a blocked turn with a structured input-required result and a visible question.NotifySend a bounded outbound alert to an operator-selected file or remote destination.Deploy and verifyDeploy the agent to Railway and verify its health, route, console, and application client.