# @kody/telegram — agent notes

Human setup and intent live in [`README.md`](./README.md). This file is for
agents: imports, smoke/dryRun execute snippets, and edge cases. Secrets by
**name** only — never paste bot tokens. Do not use Telegram Login Widget OAuth
for this package. Do not disable live webhooks or jobs (this package has none).

## Secrets

| Name | Purpose |
| --- | --- |
| `telegramBotToken` | Default Bot API token from @BotFather; host `api.telegram.org` |
| `telegramBotToken-<slug>` | Extra bot via `secretName` (lowercase letters and digits) |

Never open `/connect/oauth?provider=telegram` for Bot API work — that is Login
Widget identity only.

## Import paths

| Export | Import |
| --- | --- |
| root overview | `kody:@kody/telegram` |
| guide | `kody:@kody/telegram/guide` |
| smoke-test | `kody:@kody/telegram/smoke-test` |
| get-me | `kody:@kody/telegram/get-me` |
| get-updates | `kody:@kody/telegram/get-updates` |
| get-chat | `kody:@kody/telegram/get-chat` |
| get-webhook-info | `kody:@kody/telegram/get-webhook-info` |
| send-message | `kody:@kody/telegram/send-message` |
| request | `kody:@kody/telegram/request` |

Prefer static `kody:@kody/telegram/...` imports from `execute`. Do not lead with
`packages.invoke`.

## Smoke test (read-only)

```js
import smokeTest from 'kody:@kody/telegram/smoke-test'

export default async function main() {
	return await smokeTest()
	// Without telegramBotToken: { ok: true, live: false, setup URL }
	// With token: getMe identity — isBot: true; no messages sent
}
```

## dryRun / confirm

Pass `dryRun: true` on sends and mutating `request` calls. Live sends also
require `confirm: true` after the user approves chat and text.

```js
import sendMessage from 'kody:@kody/telegram/send-message'

export default async function main() {
	return await sendMessage({
		chatId: 123456789,
		text: 'Hello from Kody',
		dryRun: true,
	})
}
```

Read-only updates / webhook check:

```js
import getUpdates from 'kody:@kody/telegram/get-updates'
import getWebhookInfo from 'kody:@kody/telegram/get-webhook-info'

export default async function main() {
	const webhook = await getWebhookInfo()
	const updates = await getUpdates({ limit: 10 })
	return { webhook, updates }
}
```

## Errors

| Telegram response | What to do |
| --- | --- |
| 404 Not Found | `telegramBotToken` missing or empty — save at README secret URL; approve `api.telegram.org` |
| 401 Unauthorized | Save/replace `telegramBotToken`; approve `api.telegram.org` |
| 403 kicked / not a member | Add the bot to that chat (admin for channels) |
| 403 not enough rights | Grant the named chat permission — no OAuth scopes to reconnect |
| 400 chat not found | User must `/start` the bot, or add it to the group/channel |
| 409 Conflict | Webhook set or another poller running — see `get-webhook-info`; preview `deleteWebhook` with `dryRun: true` |

## Edge cases

- Bots cannot fetch arbitrary chat history — only `getUpdates` / webhook
  deliveries.
- Privacy mode (`/setprivacy`) or admin rights control group message visibility.
- Fork/adapt: save the caller's own `telegramBotToken`; keep `dryRun` /
  `confirm` guards. Never paste tokens into chat.