Telegram Bot TypeScript SDK

Type-safe TypeScript SDK for building Telegram bots, automatically generated from official Telegram Bot API documentation.

📦 Packages

This monorepo contains three packages:

@effect-ak/tg-bot-api

TypeScript types for Telegram Bot API and Mini Apps, auto-generated from official documentation.

@effect-ak/tg-bot-client

Lightweight HTTP client for Telegram Bot API with full type safety.

@effect-ak/tg-bot

Effect-based bot runner with automatic long polling and error handling.

🚀 Quick Start

HTTP Client

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("sendMessage", {
  chat_id: "123456789",
  text: "Hello, World!"
})

Bot Runner

npm install @effect-ak/tg-bot effect

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

runTgChatBot({
  bot_token: "YOUR_BOT_TOKEN",
  mode: "single",
  on_message: [
    {
      match: ({ ctx }) => ctx.command === "/start",
      handle: ({ ctx }) => ctx.reply("Welcome!")
    },
    {
      match: ({ update }) => !!update.text,
      handle: ({ update, ctx }) => ctx.reply(`You said: ${update.text}`)
    }
  ]
})

🎯 Key Features

• Always Up-to-Date: Types generated from official Telegram API documentation
• Fully Type-Safe: Complete TypeScript support for all API methods and types
• Zero Config: Works out of the box with sensible defaults
• No Webhooks Required: Uses long polling - run anywhere without public URLs

📚 Documentation

Each package has its own detailed documentation:

• API Types Documentation - TypeScript types for Bot API and Mini Apps
• Client Documentation - HTTP client usage and examples
• Bot Runner Documentation - Building bots with handlers and polling

🎮 Playground

Try it in your browser: Telegram Bot Playground

🛠️ Development

# Install dependencies
pnpm install

# Build all packages
pnpm build

# Format code
pnpm format:fix