telegram-bot-raw npm package

This package provides a minimal abstraction over the Telegram Bot API, closely follows the official specification without adding extra layers or hidden behavior.

Table of Contents

• Features
• Requirements
• Supported Bot API
• Installation
• Quick Start
• Usage
  • Calling API Methods
  • Optional Parameters
  • Methods Without Parameters
  • InputFile Object
  • Return Values
  • Error Handling
• Api Class Reference
  • Constructor
  • Properties
  • Static Properties
  • Static Methods
• License

Features

• Low-level API wrapper with minimal overhead
• Full control over API requests and parameters
• Promise-based interface
• Full TypeScript definitions
• Zero dependencies

Requirements

Node.js v18 or higher.

Supported Bot API

This package supports Telegram Bot API version 9.6
(released on April 3, 2026).

See the Telegram Bot API documentation.

Installation

npm install telegram-bot-raw

Quick Start

import { Api } from 'telegram-bot-raw';

// Create an API client instance
const botToken = '123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11';
const api = new Api(botToken);

// Get the bot's name
// (returns a BotName object defined by the Bot API spec)
const botName = await api.getMyName();

// Send a message to the user #123456789
const response = await api.sendMessage({
  chat_id: 123456789,
  text: `Greetings from <b>${botName.name}</b>!`,
  parse_mode: 'HTML'
});

// Log the sent message object
console.log('Sent message:', response);

Usage

Calling API Methods

Each Telegram Bot API method is exposed as a method of the Api class with the same name and parameters. For example, the Bot API method setMyName which accepts two string parameters name and language_code can be called as follows:

await api.setMyName({
  name: 'マイちゃんボット',
  language_code: 'jp'
});

To call an undocumented Bot API method, use the static call method, passing your Api instance, the name of the API method, and an optional object with the API call parameters. The following example uses fictitious undocumented API methods:

const api = new Api('123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11');
const userId = 123456789;

if (await Api.call(api, 'isUserWombat', { user_id: userId })) {
  await Api.call(api, 'markUserAsCute', {
    user_id: userId,
    reason: 'wombat'
  });
}

Optional Parameters

If all parameters are optional, the argument can be omitted. The following calls are equivalent:

await api.deleteWebhook({ drop_pending_updates: undefined });
await api.deleteWebhook({});
await api.deleteWebhook();

Methods Without Parameters

API methods that do not accept parameters should be called without arguments:

await api.logOut();

InputFile Object

In this library, InputFile is an alias of the native Node.js File class from node:buffer:

import { readFileSync } from 'node:fs';
import { InputFile } from 'telegram-bot-raw';

const buffer = readFileSync('photo.png');
const file = new InputFile([buffer], 'photo.png');

await api.setMyProfilePhoto({ photo: file });

See the File class documentation.

Return Values

All methods return a Promise that resolves to the result defined in the Telegram Bot API documentation.

Error Handling

If a request fails, an ApiError is thrown:

import { ApiError } from 'telegram-bot-raw';

const params = {
  message_id: 123456789,
  chat_id: 987654321,
  from_chat_id: -987654321,
};

try {
  await api.forwardMessage(params);
}
catch (error) {
  if (error instanceof ApiError) {
    console.error('Error code:', error.code);
    console.error('Error message:', error.message);
  }
}

error.code and error.message contain the error_code and description response values, respectively.

An ApiError instance may also include a parameters property corresponding to the parameters field in the server response, if present.

The raw error response from the server is available via the cause property of the ApiError instance.

Api Class Reference

Constructor

new Api(botToken: string)

• botToken: Telegram bot token.

Properties

keepAlive: boolean

Enables or disables HTTP keep-alive for requests to api.telegram.org.

Note: when using a custom request function via the transport property, the keepalive value is passed via RequestInit and handled by that function.

The default value is false.

timeout: number

Sets request timeout:

• > 0 – timeout in milliseconds,
• 0 – no timeout,
• other values are treated as 0.

If the timeout is exceeded, a TimeoutError is thrown:

api.timeout = 5000;

const params = {
  user_id: 123456789,
  chat_id: 987654321
};

try {
  await api.banChatMember(params);
}
catch (error) {
  if (error.name === 'TimeoutError')
    console.error('Server is not responding.');
  else
    throw error;
}

Note: this behavior only applies when using the default request implementation. When a custom request function is provided via the transport property, timeout handling is delegated to that function, and an AbortSignal is passed via RequestInit.signal.

The default value is 0.

transport: ApiTransport | null

Sets a function responsible for making HTTP requests to the Telegram Bot API:

function(url: string, init: RequestInit): Promise<Response>

Parameters:

• url – the full request URL.
• init – request options, including method, headers, etc.

Returns:

• A Promise that resolves to a Response object.

This can be used for logging, simulating server requests, and other tasks:

api.transport = (url, init) => {
  const method = init.method ?? 'GET';
  console.log(`${method}:`, url);
  return fetch(url, init);
}

• If transport is a Function, it will be used to send all API requests.
• If transport is null, the built-in implementation is used.
• Other values are treated as null.

The default value is null.

Static Properties

version: string

Returns the version of the Telegram Bot API supported by the library:

console.log(Api.version);  // '9.6'

Static Methods

call<T>(api: Api, method: string, params?: Record<string, any>): Promise<T>

Calls an arbitrary API method.

Parameters:

• api – an Api instance.
• method – the API method name.
• params – the API method parameters, if present.

Returns:

• A Promise that resolves to the value returned by the server.

See an example of calling undocumented methods in the Calling API Methods section.

The call method may throw an exception, see the Error Handling section.

License

• MIT