FAQ

Q: Why am I getting FLOOD_WAIT and what do I do about it?

FLOOD_WAIT_X is Telegram's rate limit: you called something too often and must wait X seconds. teleproto throws it as FloodWaitError with a .seconds field, and can auto-sleep short waits if you set floodSleepThreshold on the client. For longer waits, defer the job to your queue — never tight-loop retries, because Telegram lengthens the penalty for repeat offenders.

The questions people actually type into a search box before they find this library — answered without marketing. Deeper material is one link away on every answer.

How do I use Telegram's MTProto API from Node.js?#

Install a client library that implements the protocol — you don't hand-roll MTProto's crypto and transport yourself. With teleproto: npm install teleproto, get an api_id and api_hash from my.telegram.org, then call client.start() with your phone number. From there the whole Telegram API is available as typed TypeScript methods: send messages, read history, download media, join channels, or call any raw TL method. Start with Installation and Quick Start.

Can I use the Telegram API without a bot token?#

Yes — that's exactly what MTProto is. The Bot API (api.telegram.org, the thing most npm libraries wrap) requires a bot token and only exposes bot capabilities. MTProto is the protocol Telegram's own apps use: it logs in as a real user account with a phone number, so you can read your own chat history, manage dialogs, and access everything a human user can. teleproto also supports bot tokens if you want a bot on MTProto. The full comparison: Bot API vs MTProto.

What is a Telegram userbot and how do I build one in Node.js?#

A userbot is automation running on a regular user account instead of a bot account — it can read channels it joins, react, schedule messages, and see everything the account sees. In Node.js: create a TelegramClient with a saved session, add event handlers (NewMessage, CallbackQuery, …), and react to updates as they push in over the persistent MTProto connection. No webhook server, no public URL. The Quick Start builds one end-to-end in about ten minutes.

How is teleproto different from GramJS?#

teleproto is a 2025 fork of GramJS that kept moving: current TL layers (228 vs the layer GramJS stopped tracking), a typed class for every Telegram RPC error so you catch with instanceof, a typed client.api facade over the raw schema, email/reCAPTCHA auth flows, MTProxy fake-TLS, a rewritten network core and file pipeline. The public surface stays GramJS-compatible, so migrating is usually a one-line import swap from "telegram" to "teleproto" — see Migrating from GramJS.

Is there a Telethon equivalent for JavaScript / TypeScript?#

teleproto fills that role in the Node.js ecosystem — same concepts (sessions, entities, event builders, raw API access), same my.telegram.org credentials, but with TypeScript types generated for the entire TL schema. It even reads Telethon's 352-character session strings (IPv4 variant), so an account logged in with Telethon can be moved over without re-authenticating. Details in Sessions.

Should I use TDLib or a pure-JS MTProto library?#

TDLib is Telegram's official C++ client library — solid, but in Node.js it means native binaries or WASM builds, a JSON bridge instead of typed calls, and heavier deploys. A pure-TypeScript implementation like teleproto installs with plain npm install (no build step, works on Alpine and ARM), gives you generated types for every TL method, and keeps the whole stack debuggable in one language. TDLib makes sense when you need its exact behavior parity with official clients; for most Node.js automation the pure-JS path is simpler.

What is a Telegram session string and how do I store it safely?#

After the first login, the negotiated auth key and DC state serialize into one base64 string (StringSession). Passing it back on the next run skips the phone-code flow entirely. It is a full login credential — anyone holding it controls the account — so treat it like a password: environment variable or secret manager, never committed to git, never logged. If it leaks, terminate the session from any official Telegram client and log in fresh. The full persistence story: Sessions.

Why am I getting FLOOD_WAIT and what do I do about it?#

FLOOD_WAIT_Xis Telegram's rate limit: you called something too often and must wait X seconds. teleproto throws it as FloodWaitError with a .seconds field, and can auto-sleep short waits if you set floodSleepThreshold on the client. For longer waits, defer the job to your queue — never tight-loop retries, because Telegram lengthens the penalty for repeat offenders. Strategy and code: Errors & FloodWait.

Does teleproto run in the browser, Deno, or Bun?#

Today teleproto is server-side Node.js: the session stores and socket transports are built on Node APIs (node-localstorage, net/TLS sockets via the sockspackage). Browser support is a possible future direction — MTProto itself doesn't require raw TCP, Telegram serves WebSocket endpoints — but no browser build ships yet, so for now use a server-side bridge between your web app and teleproto. Deno and Bun aren't targeted either; their Node compatibility layers may partially work but aren't tested or supported.

Will automating my Telegram account get it banned?#

It can. Userbots violate a strict reading of Telegram's Terms of Service, and Telegram actively limits accounts that behave like spam machines: mass DMs, mass joins, participant scraping, reaction spam. Telegram signals restriction through typed frozen-account errors, which teleproto surfaces so your code can stop instead of digging deeper. Automate conservatively and use a phone number you can afford to lose. The patterns to avoid: Production.