> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tai42.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# channel-telegram

> Telegram channel plugin for the TAI ecosystem — delivers ask_user questions to a Telegram chat and bridges the typed reply back to the interactions callback door.

<Info>`Channel` plugin · listing `tai42/channel-telegram`</Info>

## Install

```bash theme={null}
tai plugins install tai42-channel-telegram
```

## Permissions

| Capability | Declared |
| ---------- | -------- |
| Network    | yes      |
| Subprocess | no       |
| Filesystem | no       |

## Provides

<h3 id="telegram">
  telegram
</h3>

`Channel` — Deliver ask\_user questions to a Telegram chat and bridge the typed reply back.

Bridge a Telegram bot to an agent, or deliver `ask_user` questions into a chat. A
message runs an agent turn and the answer comes back in the same chat.

## Enable it

```yaml manifest.yml theme={null}
channel_modules:
  - tai42_channel_telegram
```

## Configuration

The `CHANNEL_TELEGRAM_` env group. `CHANNEL_TELEGRAM_REDIS_URL` (and the
inherited connection-tuning fields) point the plugin-owned correlation store.

| Variable                                | Default | Effect                                                                                                                                   |
| --------------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `CHANNEL_TELEGRAM_BOT_TOKEN`            | unset   | Bot credential from BotFather; the auth for outbound sends. Secret.                                                                      |
| `CHANNEL_TELEGRAM_WEBHOOK_SECRET`       | unset   | Echoed by Telegram in `X-Telegram-Bot-Api-Secret-Token`; the inbound door compares it constant-time and fails closed when unset. Secret. |
| `CHANNEL_TELEGRAM_PUBLIC_BASE_URL`      | unset   | This deployment's public origin; the startup hook builds the webhook URL from it.                                                        |
| `CHANNEL_TELEGRAM_ALLOWED_RECIPIENTS`   | empty   | Whitelist of chats (numeric chat id or `@username`) a caller-supplied recipient may name. Comma-separated or JSON list.                  |
| `CHANNEL_TELEGRAM_DEFAULT_RECIPIENT`    | unset   | Chat delivered to when the caller names none; not allowlist-checked.                                                                     |
| `CHANNEL_TELEGRAM_HTTP_TIMEOUT_SECONDS` | `30`    | Wall-clock budget for one outbound HTTP call.                                                                                            |
| `CHANNEL_TELEGRAM_REDIS_URL`            | unset   | Connection for the correlation store.                                                                                                    |

## Webhook registration is automatic

Unlike the other channels, Telegram's webhook is registered **automatically**: on
startup the plugin calls `setWebhook` (idempotent) to point Telegram at
`{PUBLIC_BASE_URL}/api/channels/telegram/inbound` with the secret token. You do
not configure it by hand.

## Create a bridge route

A Telegram route's `our_identity` is the bot's **numeric id** — the digits before
the `:` in the bot token. `client_address` is the numeric chat id, so each chat
holds its own conversation:

```bash theme={null}
tai conversations create tg-chat \
  --door channel --target-name chat --execution-key chat-bot \
  --channel telegram --identity 123456
```

## See also

* [Client conversations](/concepts/client-conversations) — the bridge model and delivery outcomes.
* [Conversation bridge](/reference/conversation-bridge) — every setting and the authorization model.