Installation

Requirements#

Node 18 or newer. That's it. teleproto is pure JavaScript — no native addon, no node-gyp, no Python in your container. It installs cleanly on Alpine, ARM, and serverless runtimes that forbid a build step.

Runtime dependencies are all small and pure-JS: async-mutex, big-integer, mime, node-localstorage, socks, store2, ts-custom-error. Nothing else is pulled in.

The package is Node-only. There is no browser build, no Deno target, no Bun-specific entry. If you need to run inside a browser, this isn't the right library.

Install#

Pick your package manager:

npm install teleproto

pnpm add teleproto

yarn add teleproto

The package exposes five entry points. Use the one that matches what you're reaching for:

• teleproto — TelegramClient, Api, tl.
• teleproto/sessions — StringSession, StoreSession, MemorySession.
• teleproto/events — NewMessage, EditedMessage, CallbackQuery, Album, Raw, and the rest of the builders.
• teleproto/errors — RPCErrorand the concrete error classes you'll catch in production (FloodWaitError, FrozenError, etc).
• teleproto/tl — the parallel TL namespace, if you prefer tl.* to Api.*.

Get API credentials#

MTProto requires an app identity. Sign in at my.telegram.org/auth with your phone number, open API development tools, and create an application. You'll get back two values:

• api_id — a number. Pass it to TelegramClient as apiId: number.
• api_hash — a 32-character hex string. Pass it as apiHash: string.

Read them from environment variables. Never hard-code them into a file you might check in — see the warning below.

TG_API_ID=1234567
TG_API_HASH=0123456789abcdef0123456789abcdef

First import#

Before the full login dance, prove the package loads and a socket opens. This snippet connects to a Telegram DC without authenticating — useful as a smoke test in CI.

import { TelegramClient } from "teleproto";
import { StringSession } from "teleproto/sessions";

const apiId = Number(process.env.TG_API_ID);
const apiHash = process.env.TG_API_HASH!;

const client = new TelegramClient(new StringSession(""), apiId, apiHash, {
  connectionRetries: 5,
});

await client.connect();
console.log("connected:", client.connected);
await client.disconnect();

If that prints connected: true and exits cleanly, installation is done. For the real onboarding (sign-in, persistence, first event handler), continue to Quick Start.

TypeScript#

Types ship inside the teleproto package itself. There is no @types/teleproto to install and nothing to configure in tsconfig.json beyond what a normal Node + TS project already has. Autocomplete works on every method, event builder, and TL constructor out of the box.

One gotcha worth flagging early: numeric IDs come back as instances of the npm big-integer package — not the native bigintprimitive. Telegram's user, chat, and message IDs can exceed 2^53, so teleproto returns them as BigInteger objects with a .toString() method. Convert before logging, comparing, or passing to anything that expects a JS number:

const me = await client.getMe();
console.log(me.id.toString()); // "123456789", not [object BigInteger]

// Compare with .equals(), not ===
import bigInt from "big-integer";
if (me.id.equals(bigInt("123456789"))) { /* ... */ }