DOCSEARCHbyAlgolia
Submit Docs

GramJS Documentation

repository·master·Indexed 23 days ago

https://github.com/gram-js/gramjs

A TypeScript/JavaScript implementation of the Telegram MTProto API for building Telegram clients and automating user/bot interactions. It provides the TelegramClient for session management, the Api object for TL schema definitions, and various session implementations including MemorySession, StringSession, and StoreSession. The library includes utilities for handling RPC errors, monitoring connection states via UpdateConnectionState, and processing incoming messages with NewMessageEvent.

Tokens
1.6K
Snippets
1
Records
19
Agent score
83%

What's inside GramJS

  1. Core TL Object Types

    master

    The gramjs/tl/core module exports several fundamental Telegram Layer (TL) object types used for handling RPC results, messages, and packed data. These types are the building blocks for interacting with the Telegram API via GramJS.

    Key exported types include:

    • RPCResult: Represents the result of a Remote Procedure Call.
    • TLMessage: Represents a Telegram message object.
    • MessageContainer: A container for message-related data.
    • GZIPPacked: Represents data that has been compressed using GZIP.

  2. Apply patched TL schema definitions with patchAll()

    master
    The patchAll function applies compatibility patches to specific Telegram API classes (Api.Message, Api.MessageService, and Api.MessageEmpty). These patches inject methods, getters, and setters from CustomMessage.prototype into the prototypes of these API classes. This is typically used to ensure that standard Telegram API objects have access to enhanced functionality or custom properties provided by the CustomMessage abstraction within the library.

  3. Convert RPC errors using RPCMessageToError

    master
    When an RPC call fails, you can use RPCMessageToError to transform a raw Api.RpcError into a specific, typed error class provided by GramJS. This function iterates through known error patterns (defined in rpcErrorRe) and attempts to match the errorMessage from the Telegram response. If a match is found, it returns an instance of a specialized error class (e.g., a specific error for rate limits or authentication issues) and may capture numeric values from the error message if available.

  4. Use GramJS utility and helper modules

    master

    GramJS provides several namespaces for common tasks:

    • utils: General utility functions.
    • helpers: High-level helper functions for common Telegram operations.
    • errors: Error classes and definitions for handling Telegram-specific failures.
    • sessions: Tools for managing session strings and persistence.
    • extensions: Support for extending client functionality (e.g., Logger).
    • password: Utilities for handling password-based authentication.

  5. Use connection types in GramJS

    master

    GramJS provides several connection implementations depending on the required protocol complexity and obfuscation needs. You can import these types to manage or specify how the client connects to the Telegram servers:

    • Connection: The base interface for all connections.
    • ConnectionTCPFull: A full TCP connection implementation.
    • ConnectionTCPAbridged: An abridged version of the TCP connection.
    • ConnectionTCPObfuscated: A TCP connection that uses obfuscation to bypass network restrictions.
    import {
    Connection,
    ConnectionTCPFull,
    ConnectionTCPAbridged,
    ConnectionTCPObfuscated
} from "gramjs/network";

  6. Access core objects via coreObjects map

    master
    The coreObjects constant is a Map<number, Function> that maps Telegram constructor IDs to their corresponding class constructors. This is useful for dynamically instantiating or identifying TL objects based on their CONSTRUCTOR_ID during deserialization or processing of raw API responses.

  7. Access exported error types and utilities

    master

    The gramjs/errors module exports several categories of error handling tools:

    • Common: Common error utilities and base definitions.
    • RPCBaseErrors: The base classes for RPC-related errors.
    • RPCErrorList: The collection of specific error classes mapped to Telegram RPC error messages.

  8. Use StringSession for string-based session serialization

    master
    The StringSession class allows you to manage sessions using a string representation. This is the standard way to export a session as a string (e.g., to save in an environment variable or a database) and re-import it later to avoid re-authenticating.