{"id":16545,"library":"tdl","title":"TDLib Node.js Bindings (tdl)","description":"tdl is a JavaScript wrapper for TDLib (Telegram Database Library), providing Node.js bindings to create custom Telegram clients or bots. Currently at version 8.1.0, it is actively maintained with releases often following new TDLib versions. A key differentiator is its direct, low-level integration with the native TDLib, allowing full control over Telegram API interactions, unlike higher-level bot libraries. It requires a separate installation or build of the `tdjson` shared library from TDLib itself. tdl ships with TypeScript type definitions, enabling robust development in modern JavaScript environments.","status":"active","version":"8.1.0","language":"javascript","source_language":"en","source_url":"https://github.com/eilvelia/tdl","tags":["javascript","telegram","telegram-api","telegram-client-api","tdlib","tglib","bindings","node-addon","cucumber","typescript"],"install":[{"cmd":"npm install tdl","lang":"bash","label":"npm"},{"cmd":"yarn add tdl","lang":"bash","label":"yarn"},{"cmd":"pnpm add tdl","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Provides the `tdjson` shared library required by tdl. While optional if you build TDLib manually, it is the recommended and most convenient way to acquire the native library.","package":"prebuilt-tdlib","optional":true}],"imports":[{"note":"While `require('tdl')` in CJS returns an object where `createClient` is a property, the recommended ESM import is a named import for `createClient` directly.","wrong":"const tdl = require('tdl'); tdl.createClient(...)","symbol":"createClient","correct":"import { createClient } from 'tdl'"},{"note":"Used to specify the path to the `tdjson` shared library or configure other global settings. For ESM, it's a named import.","wrong":"const tdl = require('tdl'); tdl.configure(...)","symbol":"configure","correct":"import { configure } from 'tdl'"},{"note":"This function is provided by the separate `prebuilt-tdlib` package, not `tdl`, and is used to dynamically locate the pre-built `tdjson` shared library.","wrong":"const { getTdjson } = require('tdl')","symbol":"getTdjson","correct":"import { getTdjson } from 'prebuilt-tdlib'"},{"note":"Imports the TypeScript type definition for the `Client` instance returned by `createClient`.","symbol":"Client (type)","correct":"import type { Client } from 'tdl'"}],"quickstart":{"code":"import { createClient, configure } from 'tdl';\nimport { getTdjson } from 'prebuilt-tdlib';\n\n// IMPORTANT: Configure tdl to use the pre-built tdjson library.\n// This must be done BEFORE creating any client instances.\nconfigure({ tdjson: getTdjson() });\n\n// Replace with your actual API ID and Hash from https://my.telegram.org/\nconst apiId = Number(process.env.TELEGRAM_API_ID ?? 12345);\nconst apiHash = process.env.TELEGRAM_API_HASH ?? '0123456789abcdef0123456789abcdef';\n\nconst client = createClient({\n  apiId: apiId,\n  apiHash: apiHash\n});\n\nclient.on('error', (error) => {\n  console.error('tdl client error:', error);\n});\n\nclient.on('update', (update) => {\n  // console.log('Received update:', update);\n  if (update._ === 'updateAuthorizationState') {\n    if (update.authorization_state._ === 'authorizationStateWaitPhoneNumber') {\n      console.log('Please enter your phone number (e.g., +12345678900):');\n      // In a real app, you would prompt the user for input here\n      // For demonstration, we'll exit after waiting.\n      setTimeout(() => client.destroy(), 5000);\n    } else if (update.authorization_state._ === 'authorizationStateReady') {\n      console.log('Client is ready!');\n      client.destroy(); // Destroy client for quickstart, in real app keep running\n    }\n  }\n});\n\nconsole.log('Connecting to Telegram...');\nclient.login(() => console.log('Login initiated.'));\n","lang":"typescript","description":"Demonstrates initializing `tdl` with `prebuilt-tdlib`, creating a client, handling errors, and observing authorization state changes during login."},"warnings":[{"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' })`.","message":"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.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Ensure `prebuilt-tdlib` installs a compatible TDLib version, or if building manually, use TDLib source version 1.8.0 or newer.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Obtain your `apiId` and `apiHash` by logging in at `https://my.telegram.org/` under 'API development tools'.","message":"Valid Telegram API ID and API Hash are mandatory for `tdl.createClient()`. Using incorrect or placeholder values will result in authentication failures.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Upgrade your Node.js environment to version 16.14.0 or higher.","message":"tdl requires Node.js v16 or newer. Older Node.js versions are not supported and may lead to installation failures or runtime errors.","severity":"breaking","affected_versions":"<8.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"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' })`.","cause":"The `tdjson` shared library (`libtdjson.so`, `libtdjson.dylib`, or `tdjson.dll`) was not found in expected system paths or via configuration.","error":"Error: Cannot find tdjson library"},{"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.","cause":"The `tdl` Node.js addon failed to compile from source due to missing C++ compilers, Python, or other build dependencies.","error":"node-gyp rebuild error"},{"fix":"Verify your `apiId` and `apiHash` are correct and obtained from `https://my.telegram.org/`.","cause":"The client was initialized with incorrect `apiId` or `apiHash` values, preventing proper authorization with Telegram.","error":"updateAuthorizationState: authorizationStateWaitTdlibParameters"},{"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()`.","cause":"Incorrect import statement or attempting to use `tdl.createClient` in a CommonJS context where `tdl` might not be the expected object.","error":"TypeError: Cannot read properties of undefined (reading 'createClient') or TypeError: tdl.createClient is not a function"}],"ecosystem":"npm"}