# Telegram

Canonical: https://auggy.dev/docs/augment-telegram
Status: Published
Package: auggy 0.5.0

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

## What it enables

**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:** `transport`, `text inbound`, `text 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

1. Create a bot with @BotFather and put its token in `.env`.
2. Find the operator's numeric Telegram user ID, set `TELEGRAM_CREATOR_USER_IDS`, and send the bot a first message.
3. Run ``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.yaml**

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

**Webhook production variant**

```yaml
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 bot**

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

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

## Related

- [Add an augment](https://auggy.dev/docs/add-augment/markdown)
- [Web Transport](https://auggy.dev/docs/augment-web-transport/markdown)
- [Turn Control](https://auggy.dev/docs/augment-turn-control/markdown)
- [Notify](https://auggy.dev/docs/augment-notify/markdown)
- [Deploy and verify](https://auggy.dev/docs/deploy/markdown)