TDLib Node.js Bindings (tdl)

Common errors

• Error: Cannot find tdjson library

  cause The `tdjson` shared library (`libtdjson.so`, `libtdjson.dylib`, or `tdjson.dll`) was not found in expected system paths or via configuration.
  fix Ensure `prebuilt-tdlib` is installed and `tdl.configure({ tdjson: getTdjson() })` is called before `createClient()`, or provide a direct path via `tdl.configure({ tdjson: '/path/to/libtdjson.so' })`.

• node-gyp rebuild error

  cause The `tdl` Node.js addon failed to compile from source due to missing C++ compilers, Python, or other build dependencies.
  fix Install a C++ compiler (e.g., `build-essential` on Linux, Xcode Command Line Tools on macOS, Visual Studio Build Tools on Windows) and Python.

• updateAuthorizationState: authorizationStateWaitTdlibParameters

  cause The client was initialized with incorrect `apiId` or `apiHash` values, preventing proper authorization with Telegram.
  fix Verify your `apiId` and `apiHash` are correct and obtained from `https://my.telegram.org/`.

• TypeError: Cannot read properties of undefined (reading 'createClient') or TypeError: tdl.createClient is not a function

  cause Incorrect import statement or attempting to use `tdl.createClient` in a CommonJS context where `tdl` might not be the expected object.
  fix For ESM, use `import { createClient } from 'tdl'`. For CommonJS, use `const { createClient } = require('tdl')` if not using `tdl.configure()` first, or `const tdl = require('tdl')` and then `tdl.createClient()` after `tdl.configure()`.

Warnings

• breaking tdl requires the `tdjson` shared library of TDLib (Telegram Database Library) to be present on the system. This is a separate dependency not bundled with the `tdl` npm package.
  Fix: Install `prebuilt-tdlib` (`npm install prebuilt-tdlib`) and configure tdl using `configure({ tdjson: getTdjson() })` or manually provide the path to `libtdjson.so`/`.dylib`/`.dll` via `configure({ tdjson: '/path/to/libtdjson.so' })`.
• gotcha The `tdjson` shared library must be TDLib version 1.8.0 or newer. Using an older version can lead to crashes or unexpected behavior due to API mismatches.
  Fix: Ensure `prebuilt-tdlib` installs a compatible TDLib version, or if building manually, use TDLib source version 1.8.0 or newer.
• gotcha If pre-built Node.js addons for `tdl` are not available for your specific platform/architecture, `npm install` will attempt to build the addon from source using `node-gyp`. This requires a C++ compiler (C++14 capable), Python, and relevant build tools (e.g., MSVS on Windows) to be installed.
  Fix: Install necessary build tools for your operating system. For Windows, install 'Desktop development with C++' from Visual Studio Installer. For Linux, `build-essential` and Python. For macOS, Xcode Command Line Tools.
• gotcha Valid Telegram API ID and API Hash are mandatory for `tdl.createClient()`. Using incorrect or placeholder values will result in authentication failures.
  Fix: Obtain your `apiId` and `apiHash` by logging in at `https://my.telegram.org/` under 'API development tools'.
• breaking tdl requires Node.js v16 or newer. Older Node.js versions are not supported and may lead to installation failures or runtime errors.
  Fix: Upgrade your Node.js environment to version 16.14.0 or higher.

Install

• npm install tdl npm
• yarn add tdl yarn
• pnpm add tdl pnpm

Imports

• createClient
  wrong:

  const tdl = require('tdl'); tdl.createClient(...)

  correct:

  import { createClient } from 'tdl'

  While `require('tdl')` in CJS returns an object where `createClient` is a property, the recommended ESM import is a named import for `createClient` directly.
• configure
  wrong:

  const tdl = require('tdl'); tdl.configure(...)

  correct:

  import { configure } from 'tdl'

  Used to specify the path to the `tdjson` shared library or configure other global settings. For ESM, it's a named import.
• getTdjson
  wrong:

  const { getTdjson } = require('tdl')

  correct:

  import { getTdjson } from 'prebuilt-tdlib'

  This function is provided by the separate `prebuilt-tdlib` package, not `tdl`, and is used to dynamically locate the pre-built `tdjson` shared library.
• Client (type)

  import type { Client } from 'tdl'

  Imports the TypeScript type definition for the `Client` instance returned by `createClient`.

Quickstart

Demonstrates initializing `tdl` with `prebuilt-tdlib`, creating a client, handling errors, and observing authorization state changes during login.

import { createClient, configure } from 'tdl';
import { getTdjson } from 'prebuilt-tdlib';

// IMPORTANT: Configure tdl to use the pre-built tdjson library.
// This must be done BEFORE creating any client instances.
configure({ tdjson: getTdjson() });

// Replace with your actual API ID and Hash from https://my.telegram.org/
const apiId = Number(process.env.TELEGRAM_API_ID ?? 12345);
const apiHash = process.env.TELEGRAM_API_HASH ?? '0123456789abcdef0123456789abcdef';

const client = createClient({
  apiId: apiId,
  apiHash: apiHash
});

client.on('error', (error) => {
  console.error('tdl client error:', error);
});

client.on('update', (update) => {
  // console.log('Received update:', update);
  if (update._ === 'updateAuthorizationState') {
    if (update.authorization_state._ === 'authorizationStateWaitPhoneNumber') {
      console.log('Please enter your phone number (e.g., +12345678900):');
      // In a real app, you would prompt the user for input here
      // For demonstration, we'll exit after waiting.
      setTimeout(() => client.destroy(), 5000);
    } else if (update.authorization_state._ === 'authorizationStateReady') {
      console.log('Client is ready!');
      client.destroy(); // Destroy client for quickstart, in real app keep running
    }
  }
});

console.log('Connecting to Telegram...');
client.login(() => console.log('Login initiated.'));