Telegram Bot TypeScript SDK

Type-safe TypeScript SDK for building Telegram bots. Types are generated from the official Bot API documentation; everything else is a thin layer over native fetch with zero runtime dependencies.

Dependency chain: api ← client ← bot. Method names are snake_case exactly as in the official docs.

npm install @effect-ak/tg-bot

import { createBot } from "@effect-ak/tg-bot"

await createBot()
  .command("/start", ({ ctx }) => ctx.reply("Welcome!"))
  .onText(({ payload, ctx }) => ctx.reply(`You said: ${payload.text}`))
  .run({ bot_token: "YOUR_BOT_TOKEN" })

npm install @effect-ak/tg-bot-client

import { makeTgBotClient } from "@effect-ak/tg-bot-client"

const client = makeTgBotClient({
  bot_token: "YOUR_BOT_TOKEN"
})

await client.execute("send_message", {
  chat_id: 123456789,
  text: "Hello, World!"
})

import { createBot, defineScreens } from "@effect-ak/tg-bot"

const screens = defineScreens({
  root: { text: "Main menu", buttons: [[{ label: "Hours", next: "hours" }]] },
  hours: { text: "Mon–Fri 9–18", parent: "root" }
})

const bot = createBot().use(screens)

export default {
  fetch: (request: Request, env: Env) =>
    bot.webhook({ bot_token: env.BOT_TOKEN, secret_token: env.WEBHOOK_SECRET })(request)
}

A complete, deployable demo (several bots behind one token, KV state, GitHub Actions deploy) lives in example/.

• Always Up-to-Date: Types generated from official Telegram API documentation
• Fully Type-Safe: Complete TypeScript support for all API methods and types; errors are tagged unions
• Runs Anywhere: native fetch, no dependencies — Node.js 18+, Bun, Deno, Cloudflare Workers, browsers
• Polling or Webhooks: long polling needs no public URL; webhooks verify Telegram's secret token out of the box
• Screens: inline-keyboard navigation declared as data (defineScreens) — Back, actions, edit-in-place handled for you

Full documentation and API reference: tg-bot-sdk.website

• Introduction
• Quick Start
• API Reference

• tg-bot-sdk.website/llms.txt — index of the docs with the conventions that matter; llms-full.txt — all guides in one file
• bot-api.json / mini-app.json — machine-readable Bot API and Mini Apps specs
• Each package README documents its full API surface; repo conventions for agents are in .claude/CLAUDE.md

Try it in your browser: Telegram Bot Playground

pnpm install
pnpm build

Push to main triggers two GitHub Actions workflows:

1. Build — runs pnpm build, pnpm typecheck, and pnpm test
2. Release — runs after a successful Build, uses changesets to version and publish packages to npm

To release a new version:

1. Create a changeset: pnpm changeset
2. Commit the generated changeset file and merge to main
3. The Release workflow will open a "Release" PR that bumps versions
4. Merge the PR — packages are automatically published to npm

Packages are published with npm provenance via OIDC between GitHub Actions and npm, so every published version is cryptographically signed and linked back to its source commit and workflow run.