Wrappergram

A simple, tiny, code-generated Telegram Bot API wrapper for TypeScript. Wrappergram provides a minimal, type-safe layer over the Telegram Bot API with file upload support. It is designed for lightweight use cases — browser, serverless environments, or situations where a full framework like GramIO is overkill.

Installation

npm

npm install wrappergram

yarn

yarn add wrappergram

pnpm

pnpm add wrappergram

bun

bun install wrappergram

Quick start

import { Telegram, getUpdates } from "wrappergram";

const telegram = new Telegram(process.env.BOT_TOKEN as string);

for await (const update of getUpdates(telegram)) {
    if (update.message?.from) {
        await telegram.api.sendMessage({
            chat_id: update.message.from.id,
            text: "Hi! Thanks for the message",
        });
    }
}

API

Telegram class

The main class. Every Telegram Bot API method is available through the type-safe api proxy.

import { Telegram } from "wrappergram";

const telegram = new Telegram("BOT_TOKEN");

// Methods with no required params
const me = await telegram.api.getMe();

// Methods with required params
const response = await telegram.api.sendMessage({
    chat_id: "@gramio_forum",
    text: "Hello, world!",
});

if (!response.ok) console.error("Something went wrong");
else console.log(`Message id: ${response.result.message_id}`);

The api property returns the raw Telegram API response:

// On success:
{ ok: true, result: T }

// On failure:
{ ok: false, error_code: number, description: string }

Options

const telegram = new Telegram("BOT_TOKEN", {
    // Custom API server (default: "https://api.telegram.org/bot")
    baseURL: "https://my-custom-server.com/bot",

    // Custom fetch options
    requestOptions: {
        headers: { "X-Custom-Header": "value" },
        signal: AbortSignal.timeout(30000),
    },
});

getUpdates — Long polling

An async generator for receiving updates via long polling.

import { Telegram, getUpdates } from "wrappergram";

const telegram = new Telegram(process.env.BOT_TOKEN as string);

for await (const update of getUpdates(telegram)) {
    console.log(update);
}

WARNING

Use getUpdates only once in your code. Calling it multiple times causes duplicate getUpdates requests to the Telegram API.

File uploads

Wrappergram re-exports MediaUpload and MediaInput from @gramio/files for file handling.

MediaUpload

import { Telegram, MediaUpload } from "wrappergram";

const telegram = new Telegram("BOT_TOKEN");

// From local file path
await telegram.api.sendPhoto({
    chat_id: "@gramio_forum",
    photo: MediaUpload.path("./cute-cat.png"),
});

// From URL
await telegram.api.sendPhoto({
    chat_id: 123456,
    photo: MediaUpload.url("https://example.com/image.png"),
});

// From buffer
await telegram.api.sendDocument({
    chat_id: 123456,
    document: MediaUpload.buffer(myBuffer, "data.bin"),
});

// From text content
await telegram.api.sendDocument({
    chat_id: 123456,
    document: MediaUpload.text("Hello world", "hello.txt"),
});

MediaInput

Use MediaInput for sendMediaGroup and similar methods:

import { Telegram, MediaInput, MediaUpload } from "wrappergram";

const telegram = new Telegram("BOT_TOKEN");

await telegram.api.sendMediaGroup({
    chat_id: 123456,
    media: [
        MediaInput.document(
            MediaUpload.url("https://example.com/file.pdf")
        ),
        MediaInput.document(MediaUpload.path("./package.json")),
    ],
});

Keyboards

For inline and reply keyboards, install @gramio/keyboards:

import { Telegram } from "wrappergram";
import { InlineKeyboard } from "@gramio/keyboards";

const telegram = new Telegram("BOT_TOKEN");

await telegram.api.sendMessage({
    chat_id: "@gramio_forum",
    text: "Hello!",
    reply_markup: new InlineKeyboard().url(
        "GitHub",
        "https://github.com/gramiojs/wrappergram"
    ),
});

Types

Wrappergram re-exports all Telegram Bot API types from @gramio/types:

import type { TelegramMessage, TelegramUpdate } from "wrappergram";