tg-bot-client v0.2.0

Tg Bot Client

Tiny Telegram bot API client library (100 LOC) with TypeScript types. Automatically generated from telegram-bot-api-spec.

Changelog

Usage

Initialize bot instance with initTgBot function and call the bot methods like regular methods.

import { initTgBot } from "tg-bot-client";

const bot = initTgBot({ token: "YOUR_BOT_TOKEN" });

const me = await bot.getMe();
console.log(me.username);

const chat = await bot.getChat({ chat_id: "@durov" });
console.log(chat.title);

You can also initialize the bot everytime you call a method (it doesn't matter).

import { initTgBot } from "tg-bot-client";

const token = "YOUR_BOT_TOKEN";

const me = await initTgBot({ token }).getMe();
console.log(me.username);

const chat = await initTgBot({ token }).getChat({ chat_id: "@durov" });
console.log(chat.title);

TypeScript types are available too.

import { initTgBot } from "tg-bot-client";
import type { TgBot, TgChat, TgGetChatParams, TgUser } from "tg-bot-client";

const bot: TgBot = initTgBot({ token: "YOUR_BOT_TOKEN" });

const me: TgUser = await bot.getMe();
console.log(me.username);

const params: TgGetChatParams = { chatId: "@durov" };
const chat: TgChat = await bot.getChat(params);
console.log(chat.title);

To get updates, use the getUpdates method in a loop.

import { initTgBot } from "tg-bot-client";

const bot = initTgBot({ token: "YOUR_BOT_TOKEN" });

// Get all updates in a loop
let offset = 0;
while (true) {
  const updates = await bot.getUpdates({ offset, timeout: 30 });

  for (const update of updates) {
    // Update offset
    offset = Math.max(offset, update.update_id + 1);

    // Handle update here
  }
}

To download a file from the Telegram server you can use a special downloadFile method.

import { writeFile } from "fs/promises";
import { initTgBot } from "tg-bot-client";

const bot = initTgBot({ token: "YOUR_BOT_TOKEN" });

// Get bot photo
const botUser = await bot.getMe();
const botPhoto = await bot.getUserProfilePhotos({ user_id: botUser.id });
const botPhotoFileId = botPhoto.photos[0]?.[0]?.file_id;
const botPhotoFile = await bot.getFile({ file_id: botPhotoFileId });
const botPhotoBlob = await bot.downloadFile(botPhotoFile.file_path);

// Save bot photo locally
await writeFile("bot.jpg", botPhotoBlob.stream());

Examples

Echo bot

import { initTgBot } from "tg-bot-client";

const bot = initTgBot({ token: process.env.TG_BOT_TOKEN });

// Get all updates in a loop
let offset = 0;
while (true) {
  const updates = await bot.getUpdates({ offset, timeout: 30 });

  for (const update of updates) {
    // Update offset
    offset = Math.max(offset, update.update_id + 1);

    // Handle update about new message
    if (update.message) {
      const message = update.message;

      // Handle new private message
      if (message.chat.type === "private") {
        const username = message.from?.first_name ?? message.from?.username;
        console.log(`Received message from ${username}: ${message.text}`);

        // Only reply if message contains text
        if (message.text) {
          // Send reply
          await bot.sendMessage({
            chat_id: message.chat.id,
            text: message.text,
          });
        }
      }
    }
  }
}

FAQ

fetch is not a function

If you're using Node.js without fetch support, you need to polyfill it or pass a custom fetch as an argument.

import fetch from "node-fetch";

const bot = initTgBot({ token: "YOUR_BOT_TOKEN", fetch });

If you're sending files, you need FormData too.

import fetch, { FormData } from "node-fetch";

const bot = initTgBot({ token: "YOUR_BOT_TOKEN", fetch, FormData });

Must use import to load ES Module

The library is only available as a module. If you're using CommonJS, you must import it using dynamic import:

const { initTgBot } = await import("tg-bot-client");

Proxy is not defined

This library requires Proxy support, because the bot instance is actually a proxy.

Developing

Run npm run codegen to fetch current JSON API spec from telegram-bot-api-spec and generate TypeScript sources in src/.

Then run npm run prepare to build the sources and output JS module and typings to dist/.

After updating, commit with message "feat: update to Bot API x.y".

Finally, run npx standard-version to bump version and generate changelog.