Main bot class

Bot - the main class of the framework. You use it to interact with the Telegram Bot API.

Constructor

There are two ways to pass the token and parameters.

1. Pass the token as the first argument and (optionally) options

const bot = new Bot(process.env.BOT_TOKEN, {
    api: {
        fetchOptions: {
            headers: {
                "X-Hi-Telegram": "10",
            },
        },
    },
});

2. Pass the options with the required token field

const bot = new Bot({
    token: process.env.BOT_TOKEN,
    api: {
        fetchOptions: {
            headers: {
                "X-Hi-Telegram": "10",
            },
        },
    },
});

Bot info

When the bot begins to listen for updates, GramIO retrieves information about the bot to verify if the bot token is valid and to utilize some bot metadata. For example, this metadata will be used to strip bot mentions in commands. If you set it up, GramIO will not send a getMe request on startup.

const bot = new Bot(process.env.BOT_TOKEN, {
    info: process.env.NODE_ENV === "production" ?
		 {
					id: 1,
					is_bot: true,
					first_name:
						"Bot example",
					username: "example_bot",
                    // ..
				}
			 : undefined
    },
});

IMPORTANT

You should set this up when horizontally scaling your bot (because rate limits on getMe method and faster start up time) or working in serverless environments.

Default plugins

Some plugins are used by default, but you can disable them.

const bot = new Bot(process.env.BOT_TOKEN, {
    plugins: {
        // disable formatting. All format`` will be text without formatting
        format: false,
    },
});

API options

fetchOptions

Configure fetch parameters

const bot = new Bot(process.env.BOT_TOKEN, {
    api: {
        fetchOptions: {
            headers: {
                "X-Hi-Telegram": "10",
            },
        },
    },
});

baseURL

URL which will be used to send requests to. "https://api.telegram.org/bot" by default.

const bot = new Bot(process.env.BOT_TOKEN, {
    api: {
        // random domain
        baseURL: "https://telegram.io/bot",
    },
});

useTest

Should we send requests to test data center? false by default. The test environment is completely separate from the main environment, so you will need to create a new user account and a new bot with @BotFather.

Documentation

const bot = new Bot(process.env.BOT_TOKEN, {
    api: {
        useTest: true,
    },
});

retryGetUpdatesWait

Time in milliseconds before calling getUpdates again. 1000 by default.

const bot = new Bot(process.env.BOT_TOKEN, {
    api: {
        retryGetUpdatesWait: 300,
    },
});

Proxy support

In GramIO, it is quite simple to set up a proxy for requests.

Node.js

import { ProxyAgent } from "undici";

const proxyAgent = new ProxyAgent("my.proxy.server");

const bot = new Bot(process.env.BOT_TOKEN, {
    api: {
        fetchOptions: {
            dispatcher: proxyAgent,
        },
    },
});

WARNING

Despite the fact that undici works under the hood of Node.js, you'll have to install it. Also make sure you don't have "lib": ["DOM"] in your tsconfig.json, otherwise you won't see the dispatcher property in the types (although undici will process it anyway).

Documentation

Bun

const bot = new Bot(process.env.BOT_TOKEN, {
    api: {
        fetchOptions: {
            proxy: "https://username:password@proxy.example.com:8080",
        },
    },
});

Guide

Deno

const client = Deno.createHttpClient({
    proxy: { url: "http://host:port/" },
});

const bot = new Bot(process.env.BOT_TOKEN, {
    api: {
        fetchOptions: {
            client,
        },
    },
});

WARNING

This API is unstable, so you should run it with deno run index.ts --unstable

Documentation | Deno.proxy | HTTP_PROXY environment variables