Telegram Bot API for TypeScript

Types auto-generated from the official Telegram documentation — 285 types and 166 methods, always up to date. Zero dependencies, typed results you can pattern-match on.

Features

TypeScript Types Full type coverage for the Telegram Bot API, auto-generated from official docs.

Client Lightweight, type-safe client for calling any Bot API method.

Build Bots Run Telegram bots with long polling or webhooks.

API Reference 166 methods, 285 types — Bot API v9.5.

Getting Started

# Full bot framework (includes client and types)
npm install @effect-ak/tg-bot

# HTTP client only
npm install @effect-ak/tg-bot-client

# Types only (zero runtime code)
npm install @effect-ak/tg-bot-api

Read the Introduction or jump to Quick Start to build your first bot in under 5 minutes.

Examples

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(({ ctx }) =>
      ctx.reply(`You said: ${ctx.update.message.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"
})

const result = await client.execute("send_message", {
  chat_id: 123456,
  text: "Hello from the client!"
})

if (result.ok) {
  console.log("Sent:", result.data.message_id)
} 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()

Install with npm install @effect-ak/tg-bot-api — types only, zero runtime code.