# Telegram guide

> The fastest platform to wire up: bring a BotFather token, and registration does the rest.

## Prerequisites

- A bot created with **@BotFather** (`/newbot`) and its token.
- An AgentSky API token with write scope.

## Register the channel app

No terminal needed — the [developer console](/developer/apps/new?platform=telegram) walks the same checklist:

![The developer console's new-app checklist for Telegram: ① create a bot with BotFather, ② paste its token](/guides/channels/telegram/register-app.png)

① Message @BotFather, send `/newbot`, copy the token · ② paste it and create — the webhook is registered automatically:

![After creation the console confirms the webhook was registered and links to the app](/guides/channels/telegram/registered.png)

Or over the API:

```bash
curl -s -X POST https://agentsky.dev/api/v1/channels/apps \
  -H "Authorization: Bearer $AST_TOKEN" -H 'content-type: application/json' \
  -d '{"platform": "telegram", "label": "My bot", "credentials": {"bot_token": "123456:ABC..."}}'
```

Registration proves the token with Telegram and points the bot's webhook at a per-app ingress with a fresh secret — nothing to paste anywhere. The stored credential keys grow `bot_username` and `webhook_secret`.

## Connect

```bash
curl -s -X POST https://agentsky.dev/api/v1/channels/connections \
  -H "Authorization: Bearer $AST_TOKEN" -H 'content-type: application/json' \
  -d '{"platform": "telegram", "app": "app_...", "destination": {"session": "sess-..."}}'
```

The response's `connect.url` is a `t.me/your_bot?start=…` deep link; **Start** in the chat claims it. Links expire after 15 minutes, and a link minted for your bot is refused if opened on any other bot.

## Capabilities

| threads | reactions | markers | proactive | markdown | modals | ephemeral | streaming |
|---|---|---|---|---|---|---|---|
| ✗ | ✓ | ✓ | ✓ | ✓ | ✗ | ✗ | ✓ |

Markdown renders as Telegram MarkdownV2. Working markers use Telegram's reaction set (👀 while working, 👍 done, 💔 failed — Telegram only allows a fixed reaction list).

## Troubleshooting

- **App creation answers 400 `telegram_error`** — the token failed `getMe`; re-copy it from BotFather.
- **The deep link says it belongs to a different bot** — it was minted for another channel app; mint a new connection with the right `app`.
- **Nothing arrives from a group** — add the bot to the group and mention it (or message it directly); group privacy rules apply until the bot is engaged.