# teleproto

> Telegram MTProto API client library written in TypeScript. Documentation for userbots, automation, sessions, events, and the raw TL surface.

teleproto is a Telegram MTProto API client library written in TypeScript for Node.js. It is ideologically inspired by GramJS and remains GramJS-compatible for most public API. Source: https://github.com/sanyok12345/teleproto. Package on npm: `teleproto` (current version 1.229.0, published 2026-08-25). Full API reference: https://ref.teleproto.dev.

## Getting Started

- [Introduction](https://docs.teleproto.dev/)
- [Installation](https://docs.teleproto.dev/installation)
- [Quick Start](https://docs.teleproto.dev/quick-start)
- [Authentication](https://docs.teleproto.dev/authentication)
- [Sessions](https://docs.teleproto.dev/sessions)
- [Migrating from GramJS](https://docs.teleproto.dev/migrating-from-gramjs)
- [FAQ](https://docs.teleproto.dev/faq)

## Concepts

- [Entities & Peers](https://docs.teleproto.dev/concepts/entities)
- [Updates & Events](https://docs.teleproto.dev/concepts/updates)
- [Errors & FloodWait](https://docs.teleproto.dev/concepts/errors)
- [Raw TL API](https://docs.teleproto.dev/concepts/raw-api)
- [Bot API vs MTProto](https://docs.teleproto.dev/concepts/bot-api-vs-mtproto)

## Guides

- [Messages](https://docs.teleproto.dev/guides/messages)
- [Media](https://docs.teleproto.dev/guides/media)
- [Chats & Channels](https://docs.teleproto.dev/guides/chats)
- [Events](https://docs.teleproto.dev/guides/events)

## Operations

- [Production](https://docs.teleproto.dev/production)

## Internals

- [Connection lifecycle](https://docs.teleproto.dev/internals/connection)
- [Auth keys & encryption](https://docs.teleproto.dev/internals/auth-keys)
- [Entity cache](https://docs.teleproto.dev/internals/entity-cache)
- [File transfer](https://docs.teleproto.dev/internals/file-transfer)
- [Update pipeline](https://docs.teleproto.dev/internals/updates)

## Reference

- [API Reference ↗](https://ref.teleproto.dev)

## Key facts for code generation

- Package name on npm: `teleproto` (current version 1.229.0). Server-side Node.js today (uses `node-localstorage`, `socks`); no browser/Deno/Bun build yet — browser support is a possible future direction.
- Install: `npm install teleproto`. Subpath imports: `teleproto`, `teleproto/sessions`, `teleproto/events`, `teleproto/errors`, `teleproto/tl`.
- Entry class: `TelegramClient` from `teleproto`. Constructor: `new TelegramClient(session, apiId, apiHash, params)`.
- Sessions: `StringSession`, `StoreSession`, `MemorySession` from `teleproto/sessions`. Use `new StringSession("")` for fresh login.
- Auth: `await client.start({ phoneNumber, phoneCode, password?, onError })` for users, `await client.start({ botAuthToken })` for bots.
- Events: `client.addEventHandler(callback, new NewMessage({...}))`. Builders from `teleproto/events`: NewMessage, EditedMessage, DeletedMessage, CallbackQuery, InlineQuery, Album, ChatAction, MessageRead, UserUpdate, Raw.
- Raw TL, two equivalent ways: typed facade `await client.api.messages.sendMessage({...})` (camelCase, fully typed params+result, preferred), or `await client.invoke(new Api.messages.SendMessage({...}))`. `Api` namespace exported from `teleproto`.
- Nested TL objects accept plain literals with a `_` tag (mtproto-core style): `{ invoice: { _: "inputInvoiceSlug", slug } }` coerces to the generated class at serialization; `_` optional when the type has one constructor; `randomId` fields auto-generate when omitted.
- IDs are `bigInt` from the npm `big-integer` package, NOT native `BigInt`. Call `.toString()` to print.
- No middleware, no dispatcher, no Conversation helper, no FSM. Pure event handlers.
- Every Telegram RPC error is a typed class in `teleproto/errors` (also `errors` namespace from `teleproto`): catch via `instanceof` — `FloodWaitError` (.seconds), `SlowModeWaitError` (.seconds), `SessionRevokedError`, `AuthKeyUnregisteredError`, `ChannelPrivateError`, `FrozenMethodInvalidError`, `UserMigrateError` (.newDc), etc. Unknown/newer codes fall back to the HTTP-code base class (`UnauthorizedError`, `FloodError`, ...); `error.errorMessage` always holds the raw server string.
- `markAsRead(entity, msgId?, { clearMentions? })` — NOT `sendReadAcknowledge` (that was GramJS).
- Logout: `await client.logOut()` (revokes server-side AND wipes local session).
- Entity cache is bounded (LRU, 4096 peers/segment) by default; tune with `entityCache: true | false | { max, ttl }` on TelegramClientParams.
- Parse modes: `parseMode: "html" | "md"`. HTML supports <b> <i> <code> <a> <br> <tg-emoji> <blockquote expandable> <tg-date> and tg://user?id= mentions; all HTML5 entities decoded.
- Proxies: SOCKS5 and MTProxy (both `dd`-padded and `ee` fake-TLS secrets) via the `proxy` client param. No HTTP proxy.

Full compressed documentation for LLM context windows: https://docs.teleproto.dev/llms-full.txt

Last regenerated: 2026-09-10T07:47:38.852Z