# @kody/telegram

Official Telegram paper-plane mark from [telegram.org/img/t_logo.svg](https://telegram.org/img/t_logo.svg).

## Intent

Provide reusable, account-agnostic Telegram Bot API helpers so Kody can read
updates and chats a bot can see, and send explicitly confirmed messages, using
a saved `telegramBotToken` — never Telegram Login Widget OAuth.

## What it does

- Read bot identity (`getMe`), chat metadata, webhook info, and polled updates
- Preview or send messages with `dryRun` / `confirm` guards
- Escape-hatch `request` for any Bot API method
- Guide export with BotFather steps and the prefilled secret URL

## Prerequisites / setup

### Auth: bot token, not OAuth, not an API key

This package calls `https://api.telegram.org/bot<token>/METHOD`. That token is
created by [@BotFather](https://t.me/botfather). It is **not** an OAuth access
token and **not** a user account password.

Do **not** connect `https://kody.codes/connect/oauth?provider=telegram` for this
package. That URL is Telegram Login Widget identity (`openid` / `profile` on
`oauth.telegram.org`) and cannot send or read Bot API messages.

Telegram Bot API has **no OAuth scopes**. What the bot can do is:

- chat membership (private chats require the user to send `/start`)
- admin rights in groups and channels
- BotFather privacy mode (`/setprivacy`) for reading non-command group messages

If Telegram returns 401/403, the error names the missing access and the next
setup step.

### Required setup

1. Open Telegram and message [@BotFather](https://t.me/botfather).
2. Send `/newbot` (or `/token` for an existing bot) and copy the token. Never
   paste the token into chat.
3. Save it in Kody and approve host `api.telegram.org`:

https://kody.codes/account/secrets/new?name=telegramBotToken&description=Telegram%20Bot%20API%20token%20from%20%40BotFather&allowedHosts=api.telegram.org&scope=user

4. Send `/start` to the bot in a private chat. Add the bot to groups you want
   it in. For channels, add it as an administrator.
5. To read **all** group messages (not just commands and replies), either:
   - @BotFather → `/setprivacy` → **Disable**, or
   - make the bot a group administrator.
6. Smoke-test (see [`AGENTS.md`](./AGENTS.md)).

Required host: `api.telegram.org`.

### Additional bots

Default secret name is `telegramBotToken`. Pass
`secretName: "telegramBotToken-<slug>"` (lowercase letters and digits) for
another bot, and save that secret with the same host:

https://kody.codes/account/secrets/new?name=telegramBotToken-alerts&description=Telegram%20Bot%20API%20token%20from%20%40BotFather&allowedHosts=api.telegram.org&scope=user

### Mutation safety

Mutations never call Telegram when `dryRun: true`. Live sends require
`confirm: true` after the user explicitly approves the chat and text.

Agents: see [`AGENTS.md`](./AGENTS.md) for import paths, smoke checks, confirm
guards, and error tables.

## Done when

- `telegramBotToken` is saved; host `api.telegram.org` is approved
- Smoke test returns `ok: true` (live `getMe` with `isBot: true` when the token
  exists)
- Sends refuse unless `confirm: true`; `dryRun: true` never posts

## Branding

`community-icon.svg` is Telegram's official paper-plane mark from
[telegram.org/img/t_logo.svg](https://telegram.org/img/t_logo.svg). Telegram is
a trademark of Telegram FZ-LLC. This package is not affiliated with or endorsed
by Telegram.