GramJS

GramJS is a JavaScript/TypeScript implementation of Telegram’s MTProto protocol, published to npm as the telegram package. It ports the design of Python’s Telethon library to the Node.js and browser ecosystem, giving developers direct access to Telegram’s raw client API rather than the restricted surface exposed by the official Bot API. That means GramJS can log in as a real user account, read and send messages in any chat the account belongs to, manage channels and groups, upload and download media, and invoke any of the thousands of raw MTProto methods through a generic client.invoke() call.

Because it speaks MTProto directly, GramJS handles the encrypted transport layer itself: authentication key generation, TCP/obfuscated/WebSocket connections depending on runtime, session persistence (string or store-backed), and automatic reconnect/retry logic for flood waits and internal Telegram errors. This makes it the standard choice for building userbots, automation scripts, chat exporters, and Telegram-integrated tooling where the official Bot API’s permission model is too limiting.

What You Get

• A TelegramClient class handling connection setup, authentication key exchange, and session persistence via StringSession or StoreSession
• High-level helpers (sendMessage, getDialogs, downloadMedia, iterMessages) layered over the raw MTProto API for common chat operations
• Direct access to the full raw Telegram API surface via client.invoke(new Api.SomeRequest(...)) for anything the high-level helpers don’t cover
• Built-in event system (NewMessage, Raw, and other event builders) for reacting to incoming updates in real time
• Cross-environment networking with TCP/obfuscated connections on Node.js and WebSocket transport in browsers
• Markdown and HTML message-formatting parsers for constructing rich text messages

Common Use Cases

• Building Telegram userbots that automate actions on a personal or business account beyond what the official Bot API allows
• Exporting or archiving message history, media, and metadata from channels and chats a user account belongs to
• Bridging Telegram conversations into other systems (support desks, notification pipelines, custom dashboards)
• Prototyping browser-based Telegram clients or embedded chat widgets using the same client against the WebSocket transport

Under The Hood

Architecture

GramJS layers a promise-based TelegramClient (src/gramjs/client/telegramBaseClient.ts, TelegramClient.ts) over an MTProtoSender (network/) that owns the encrypted transport, choosing ConnectionTCPFull/ConnectionTCPObfuscated on Node or PromisedWebSockets in the browser via runtime detection in platform.ts. Raw TL schema types live under gramjs/tl (generated from api.tl definitions, AllTLObjects.ts tracks the active protocol LAYER), and higher-level methods (client/messages.ts, client/chats.ts, client/downloads.ts, client/uploads.ts) are thin wrappers that construct and invoke() these raw Api.* request objects. Sessions (gramjs/sessions) abstract auth-key/DC storage behind StringSession/StoreSession so a client can reconnect without re-authenticating, and an EntityCache plus event system (gramjs/events) sit on top to resolve peers and dispatch incoming updates to registered handlers.

Tech Stack

Written in TypeScript (~70% of the codebase) compiled via the TypeScript compiler and Babel for the Jest test pipeline, published under the telegram npm package name at version 2.26.x. Runtime dependencies include @cryptography/aes and its own crypto/ implementation for MTProto’s custom AES-IGE and key-exchange primitives, big-integer for the arbitrary-precision math MTProto requires, socks/websocket for the two supported transports, async-mutex for connection-level locking (Semaphore), pako for gzip payload decompression, and htmlparser2/ts-custom-error for message formatting and typed error classes respectively. Browser bundling is handled via a dedicated webpack.config.js and generate_webpack.js script, and the package ships prebuilt .d.ts type declarations from its own tsconfig.json build.

Code Quality

Test coverage is narrow: tests/ contains 7 Jest spec files (crypto/AES, crypto/factorizator, crypto/calcKey, crypto/readBuffer, extensions/HTML, Markdown, MarkdownV2) exercising cryptographic primitives and message-format parsers, but the much larger client/network/tl surface (TelegramClient.ts alone is ~1,580 lines) has no direct unit tests, relying instead on manual/integration verification against live Telegram servers. Errors are modelled with typed classes under gramjs/errors (RPCBaseErrors, a generated RPCErrorList) rather than raw strings, and naming is consistent with the upstream Telethon (Python) API it was ported from. A GitHub Actions CI workflow runs npm test on push/PR, but the project’s own README now flags it as archived with no further maintenance, so code quality here should be read as a frozen snapshot rather than an actively hardened codebase.

API Design

The public API centers on a single TelegramClient(session, apiId, apiHash, params) constructor with a documented TelegramClientParams interface (JSDoc on every option), and getting a first message sent requires only a handful of lines: construct the client, call start() with phone/code/password callbacks, then sendMessage('me', {...}). High-level methods like sendMessage, getDialogs, and downloadMedia cover the common 80% of use cases with plain-object options, while client.invoke(new Api.SomeRequest(...)) provides an escape hatch to the complete raw API for advanced needs — a two-tier design that keeps onboarding simple without sacrificing capability. The main friction point for newcomers is that raw API usage requires cross-referencing Telegram’s own TL schema documentation, and interactive login (phone/2FA callbacks) adds boilerplate compared to bot-token style SDKs.