@effect-ak/tg-bot-client

Type-safe HTTP client for Telegram Bot API with complete TypeScript support.

Table of Contents

• Motivation
• Features
• Installation
• Quick Start
• Usage Examples
  • Sending Messages
  • Sending Files
  • Downloading Files
  • Using Message Effects
• Error Handling
• API Reference
• Configuration
• Related Packages
• Contributing
• License

Motivation

Telegram does not offer an official TypeScript SDK for their API but they provide documentation in HTML format.

This package provides a lightweight, type-safe HTTP client that uses types generated from the official Telegram Bot API documentation, ensuring it stays in sync with the latest API updates.

Features

• Type-Safe: Full TypeScript support with types generated from official documentation
• Lightweight: Minimal dependencies
• Complete API Coverage: All Bot API methods are supported
• Smart Type Conversion: Automatic mapping of Telegram types to TypeScript:
  • Integer → number
  • True → boolean
  • String or Number → string | number
  • Enumerated types → Union of literal types (e.g., "private" | "group" | "supergroup" | "channel")
• File Handling: Simplified file upload and download
• Message Effects: Built-in constants for message effects
• Custom Base URL: Support for custom Telegram Bot API servers

Installation

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

pnpm add @effect-ak/tg-bot-client

yarn add @effect-ak/tg-bot-client

Quick Start

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

const client = makeTgBotClient({
  bot_token: "YOUR_BOT_TOKEN" // Token from @BotFather
})

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

Usage Examples

Sending Messages

Basic Text Message

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

Message with Formatting

await client.execute("send_message", {
  chat_id: "123456789",
  text: "*Bold* _italic_ `code`",
  parse_mode: "Markdown"
})

Message with Inline Keyboard

await client.execute("send_message", {
  chat_id: "123456789",
  text: "Choose an option:",
  reply_markup: {
    inline_keyboard: [
      [
        { text: "Option 1", callback_data: "opt_1" },
        { text: "Option 2", callback_data: "opt_2" }
      ]
    ]
  }
})

Sending Files

Sending a Dice

await client.execute("send_dice", {
  chat_id: "123456789",
  emoji: "🎲"
})

Sending a Document

await client.execute("send_document", {
  chat_id: "123456789",
  document: {
    file_content: new TextEncoder().encode("Hello from file!"),
    file_name: "hello.txt"
  },
  caption: "Simple text file"
})

Sending a Photo

await client.execute("send_photo", {
  chat_id: "123456789",
  photo: {
    file_content: photoBuffer,
    file_name: "image.jpg"
  },
  caption: "Check out this photo!"
})

Downloading Files

To download a file from Telegram servers, use the getFile method. It handles both the API call and file download in one step:

// Get file by file_id (from a message, for example)
const file = await client.getFile({
  file_id: "AgACAgIAAxkBAAI..."
})

// file is a standard File object
console.log(file.name) // filename.jpg
console.log(file.size) // file size in bytes

// Read file contents
const arrayBuffer = await file.arrayBuffer()
const text = await file.text()
const blob = await file.blob()

Using Message Effects

The library includes built-in constants for message effects:

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

await client.execute("send_message", {
  chat_id: "123456789",
  text: "Message with fire effect!",
  message_effect_id: MESSAGE_EFFECTS["🔥"]
})

Available effects:

• MESSAGE_EFFECTS["🔥"] - Fire
• MESSAGE_EFFECTS["👍"] - Thumbs up
• MESSAGE_EFFECTS["👎"] - Thumbs down
• MESSAGE_EFFECTS["❤️"] - Heart
• MESSAGE_EFFECTS["🎉"] - Party
• MESSAGE_EFFECTS["💩"] - Poop

Error Handling

The client throws TgBotClientError for all errors:

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

try {
  await client.execute("send_message", {
    chat_id: "invalid",
    text: "Test"
  })
} catch (error) {
  if (error instanceof TgBotClientError) {
    console.error("Error type:", error.cause._tag)

    switch (error.cause._tag) {
      case "NotOkResponse":
        console.error("API error:", error.cause.errorCode, error.cause.details)
        break
      case "UnexpectedResponse":
        console.error("Unexpected response:", error.cause.response)
        break
      case "ClientInternalError":
        console.error("Internal error:", error.cause.cause)
        break
      case "UnableToGetFile":
        console.error("File download error:", error.cause.cause)
        break
      case "NotJsonResponse":
        console.error("Invalid JSON response:", error.cause.response)
        break
    }
  }
}

API Reference

makeTgBotClient(config)

Creates a new Telegram Bot API client.

Parameters:

• config.bot_token (string, required): Your bot token from @BotFather
• config.base_url (string, optional): Custom API base URL (default: https://api.telegram.org)

Returns: TgBotClient

client.execute(method, input)

Executes a Telegram Bot API method.

Parameters:

• method (string): API method name in snake_case (e.g., "send_message", "get_updates")
• input (object): Method parameters as defined in Telegram Bot API

Returns: Promise<ApiResponse> - Typed response based on the method

Note: Method names use snake_case (e.g., send_message) instead of camelCase for better readability and consistency with the Telegram API documentation.

client.getFile(input)

Downloads a file from Telegram servers.

Parameters:

• input.file_id (string): File identifier from a message

Returns: Promise<File> - Standard File object

Configuration

Custom Base URL

If you're running your own Telegram Bot API server:

const client = makeTgBotClient({
  bot_token: "YOUR_BOT_TOKEN",
  base_url: "https://your-custom-server.com"
})

Related Packages

This package is part of the tg-bot-client monorepo:

• @effect-ak/tg-bot-api - TypeScript types for Telegram Bot API and Mini Apps
• @effect-ak/tg-bot - Effect-based bot runner for building Telegram bots
• @effect-ak/tg-bot-codegen - Code generator that parses official documentation

Contributing

Contributions are welcome! Please check out the issues or submit a pull request.

License

MIT © Aleksandr Kondaurov