Telegram Bot API for TypeScript

Type-safe SDK for building Telegram bots — auto-generated types, lightweight client, zero runtime dependencies.

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

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

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

// full type safety for params and result
const message = await client.execute("send_message", {
  chat_id: 123456,
  text: "Hello from the client!"
})

console.log("Sent:", message.message_id)

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

createBot()
  .onMessage(({ command, text }) => [
    command("/start", ({ ctx }) =>
      ctx.reply("Hello! I'm your new bot")
    ),
    text(({ ctx }) =>
      ctx.reply(`You said: ${ctx.update.message.text}`)
    )
  ])
  .run({ bot_token: "YOUR_BOT_TOKEN" })

import type { WebApp } from "@effect-ak/tg-bot-api"

declare const Telegram: { WebApp: WebApp }

const app = Telegram.WebApp
app.ready()

app.MainButton.setText("Submit")
app.MainButton.onClick(() => {
  app.sendData(JSON.stringify({ action: "submit" }))
})
app.MainButton.show()

400TypeScript types

185API methods

0Runtime dependencies

100%Generated from official docs

Why this SDK

Everything typed, nothing heavy

Three small packages that cover the whole Bot API surface — from raw types to a full bot runner.

Auto-generated types

400 types and 185 methods scraped from the official Telegram docs — regenerated on every Bot API release.

End-to-end type safety

Every method knows its params and return type. Autocomplete in your editor instead of hopping to the docs.

Zero dependencies

Native fetch, no runtime deps. Runs on Node.js, Bun, Deno, and edge runtimes like Cloudflare Workers.

Long polling & webhooks

Develop locally with long polling, deploy to serverless with webhooks — same handlers, no code changes.

Typed error handling

Discriminated unions instead of thrown surprises. Match on error tags and let the compiler check every branch.

Mini Apps support

Typed Telegram.WebApp API for building Mini Apps — buttons, haptics, themes, and more.

Examples

See it in code

A full bot, a bare client call, or just the types — the API stays small at every layer.

Create a bot with command handling and text replies — no middleware, no boilerplate.

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

createBot()
  .onMessage(({ command, text }) => [
    command("/start", ({ ctx }) =>
      ctx.reply("Hello! I'm your new bot.")
    ),
    text(({ payload, ctx }) =>
      ctx.reply(`You said: ${payload.text}`)
    )
  ])
  .run({ bot_token: "YOUR_BOT_TOKEN" })

Install with npm install @effect-ak/tg-bot — includes the client and all types.

Call any Bot API method directly with full type safety and typed error handling.

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

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

// throws TgBotClientError on failure
const message = await client.execute("send_message", {
  chat_id: 123456,
  text: "Hello from the client!"
})

console.log("Sent:", message.message_id)

// or the non-throwing variant
const result = await client.executeSafe("get_me", {})

if (result.ok) console.log("Bot:", result.data.first_name)
else console.log("Error:", result.error._tag)

Install with npm install @effect-ak/tg-bot-client — lightweight client without the bot runner.

Use auto-generated TypeScript types for the Telegram.WebApp API in your Mini App.

import type { WebApp } from "@effect-ak/tg-bot-api"

declare const Telegram: { WebApp: WebApp }

const app = Telegram.WebApp
app.ready()

app.MainButton.setText("Submit")
app.MainButton.onClick(() => {
  app.sendData(JSON.stringify({ action: "submit" }))
})
app.MainButton.show()