@kody/telegram

Read Telegram chats the bot can see and send confirmed messages through the Bot API using telegramBotToken.

AGENTS.md

94 lines · 3.1 KB · Markdown

@kody/telegram — agent notes

Human setup and intent live in 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)

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.

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:

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.