@kody/telegram

@kody/telegram

Official Telegram paper-plane mark from 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.

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. 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.
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. Run the smoke test below.

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

Smoke test

./smoke-test is safe before anyone saves a token: it returns { ok: true, live: false } and the setup URL. After telegramBotToken and host approval, invoke the package (not a static import) so the secret placeholder resolves and getMe runs:

import { packages } from 'kody:runtime'

export default async function main() {
	return await packages.invoke({
		kodyId: 'telegram',
		exportName: './smoke-test',
	})
}

A live result is getMe with isBot: true. It does not send messages.

dryRun

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

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

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

Exports

• kody:@kody/telegram — package overview and safety metadata
• kody:@kody/telegram/guide — BotFather steps and the prefilled secret URL
• kody:@kody/telegram/smoke-test — getMe identity check
• kody:@kody/telegram/get-me — authenticated bot profile
• kody:@kody/telegram/get-updates — poll delivered updates (not arbitrary history)
• kody:@kody/telegram/get-chat — one chat the bot can see
• kody:@kody/telegram/get-webhook-info — whether a webhook is blocking getUpdates
• kody:@kody/telegram/send-message — preview or send; sending requires confirm: true
• kody:@kody/telegram/request — any Bot API method; mutating calls need dryRun / confirm

Bots cannot fetch arbitrary chat history. They only see messages Telegram delivers through getUpdates or a webhook. If getUpdates returns 409, a webhook is set: read get-webhook-info, then request({ method: 'deleteWebhook', dryRun: true }).

Errors