@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.

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. 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. Smoke-test (see 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 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. Telegram is a trademark of Telegram FZ-LLC. This package is not affiliated with or endorsed by Telegram.