# tdlib-native

> 🚀 Telegram TDLib native nodejs wrapper

Latest version **3.8.0** (published 2025-08-21) · MIT license · 0 weekly downloads

## Install

```sh
npm install tdlib-native
pnpm add tdlib-native
yarn add tdlib-native
bun add tdlib-native
```

## Health

**Score 55/100 (C)** — status: stable.

Positive: has types; esm support; no vulnerabilities; has provenance; high quality score.

Warnings: low downloads.

Negative: stale.

## Facts

| | |
|---|---|
| Version | 3.8.0 |
| Published | 2025-08-21 |
| First published | 2023-02-08 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=16 |
| Dependencies | 2 |
| Unpacked size | 9.3 MB |
| Known vulnerabilities | 0 |
| Install scripts | yes |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 6 |
| Author | Alexander |
| Maintainers | alexxandergrib |
| Keywords | telegram, tdlib, tdl, node, backend |

## Links

- npm: https://www.npmjs.com/package/tdlib-native
- Repository: https://github.com/AlexXanderGrib/node-tdlib
- Homepage: https://github.com/AlexXanderGrib/node-tdlib#readme
- Issues: https://github.com/AlexXanderGrib/node-tdlib/issues
- npm.io page: https://npm.io/package/tdlib-native

## Dependencies (2)

- [debug](https://npm.io/package/debug.md) ^4.4.1
- [node-addon-api](https://npm.io/package/node-addon-api.md) ^8.5.0

## Alternatives

- [@expo/fingerprint](https://npm.io/package/@expo/fingerprint.md) — 6.2M weekly downloads
- [@azure/monitor-opentelemetry-exporter](https://npm.io/package/@azure/monitor-opentelemetry-exporter.md) — 850.0K weekly downloads
- [@azure/monitor-opentelemetry](https://npm.io/package/@azure/monitor-opentelemetry.md) — 624.0K weekly downloads
- [@posthog/ai](https://npm.io/package/@posthog/ai.md) — 423.3K weekly downloads
- [fakefilter](https://npm.io/package/fakefilter.md) — 63.9K weekly downloads

## Recent versions

- 3.8.0 (latest) — 2025-08-21
- 3.7.1 — 2025-08-06
- 3.7.0 — 2025-08-06
- 3.6.0 — 2025-07-30
- 3.5.0 — 2025-03-29
- 3.4.1 — 2025-01-28
- 3.4.0 — 2025-01-28
- 3.3.0 — 2025-01-09
- 3.2.0 — 2024-11-01
- 3.1.0 — 2024-10-21
- 3.0.0 — 2024-10-19
- 2.7.0 — 2024-08-15
- 2.6.0 — 2024-07-16
- 2.5.0 — 2024-07-09
- 2.4.0 — 2024-06-19
- … 29 more at https://npm.io/package/tdlib-native/versions

## README

# TDLib Native

> Cross platform TDLib wrapper

<img src="https://alexxandergrib.github.io/node-tdlib/icons/tdlib-native-logo.svg" align="right"
     alt="Logo" width="96" height="96">

[![Test Status](https://github.com/AlexXanderGrib/node-tdlib/actions/workflows/test.yml/badge.svg)](https://github.com/AlexXanderGrib/node-tdlib)
[![Downloads](https://img.shields.io/npm/dt/tdlib-native.svg)](https://npmjs.com/package/tdlib-native)
[![last commit](https://img.shields.io/github/last-commit/AlexXanderGrib/node-tdlib.svg)](https://github.com/AlexXanderGrib/node-tdlib)
[![codecov](https://img.shields.io/codecov/c/github/AlexXanderGrib/node-tdlib/main.svg)](https://codecov.io/gh/AlexXanderGrib/node-tdlib)
[![GitHub](https://img.shields.io/github/stars/AlexXanderGrib/node-tdlib.svg)](https://github.com/AlexXanderGrib/node-tdlib)
[![tdlib-native](https://snyk.io/advisor/npm-package/tdlib-native/badge.svg)](https://snyk.io/advisor/npm-package/tdlib-native)
[![Known Vulnerabilities](https://snyk.io/test/npm/tdlib-native/badge.svg)](https://snyk.io/test/npm/tdlib-native)
[![npm](https://img.shields.io/npm/v/tdlib-native.svg)](https://npmjs.com/package/tdlib-native)
[![license MIT](https://img.shields.io/npm/l/tdlib-native.svg)](https://github.com/AlexXanderGrib/node-tdlib/blob/main/LICENSE.txt)
[![Size](https://img.shields.io/bundlephobia/minzip/tdlib-native)](https://bundlephobia.com/package/tdlib-native)

## Why use this package?

- **Fast.** `TDLib` is a fastest way to interact with Telegram on NodeJS. It's written in C++ with optimized network stack and caching.
- **Better DX.** Easy, well documented API. Instant type completion
  ```typescript
  /**
   * Sends a message. Returns the sent message
   *
   * @throws {TDError}
   * @param {sendMessage$DirectInput} parameters {@link sendMessage$Input}
   * @returns {Promise<Message>} Promise<{@link Message}>
   */
  async sendMessage(parameters: sendMessage$DirectInput): Promise<Message>
  ```
- **Secure.**
  - Only 3 dependencies: `node-addon-api`, `debug`, `detect-libc`
  - Built on CI with provenance
- **Multi-Platform.** Supported platforms:
  - Linux: x64, arm64 (glibc, musl)
  - Android: arm64 (glibc, musl)
  - MacOS: x64, Apple Silicon (arm64)
  - Windows: x64, x32

## 📦 Installation

- **Using `npm`**
  ```shell
  npm i tdlib-native
  ```
- **Using `Yarn`**
  ```shell
  yarn add tdlib-native
  ```
- **Using `pnpm`**
  ```shell
  pnpm add tdlib-native
  ```

## 3.0 Changelog

- Made builds for linux arm64
- Made builds for musl libc
- Made builds for windows x32 (since tg desktop supports it)
- Fixed client thread safety, fixed disposal of tdlib clients
- Made `client.start()`, `client.pause()` and `client.destroy()` - async
- Upgraded TDLib to 1.8.37

## ⚙️ Usage

This is raw wrapper of TDLib

```typescript
import { Client, Authenticator } from "tdlib-native";
import { TDLibAddon } from "tdlib-native/addon";

async function init() {
  // Loading addon
  const adapter = await TDLibAddon.create();

  // Make TDLib shut up. Immediately
  Client.disableLogs(adapter);

  const client = new Client(adapter);
  const authenticator = Authenticator.create(client)
    .tdlibParameters({
      /* options */
    })
    .token(process.env.TELEGRAM_BOT_TOKEN);

  // Start polling responses from TDLib
  // And authenticate bot
  // THIS SHOULD BE USED via Promise.all
  // OR ELSE .authenticate() skips an update and hangs
  await Promise.all([client.start(), authenticator.authenticate()]);

  // client authorized as bot
  // Call any tdlib method
  await client.api.getOption({ name: "version" });
  // => Promise { _: "optionValueString", value: "1.8.37" }

  // or use a wrapper
  await client.tdlibOptions.get("version");
  // => Promise "1.8.22"

  // Subscribe to updates
  client.updates.subscribe(console.log);

  // Pause receiving updates. Will freeze method all running API calls
  // await client.pause();
  // Resume pause
  // await client.start();

  // Destroy
  await client.api.close({});
  await client.destroy();
}
```

**Usage with RxJS**

```typescript
// Observable will complete after client.destroy() call
const updates = new Observable(client.updates.toRxObserver());
```

### Projects built with `tdlib-native`

<table><tbody><tr><td align="center" valign="top" width="11%">
<a href="https://t.me/guardcore_bot">
<img
src="https://alexxandergrib.github.io/node-tdlib/icons/guardcore-bot.jpg"
width="75"
height="75"
alt="GuardCore Bot's Avatar"
/><br />
GuardCore Bot
</a>
</td><td align="center" valign="top" width="11%">
<a href="https://t.me/tvoya_statya_bot">
<img
src="https://alexxandergrib.github.io/node-tdlib/icons/tvoya-statya-bot.jpg"
width="75"
height="75"
alt="Твоя Статья УК РФ's Avatar"
/><br />
Твоя Статья УК РФ
</a>
</td><td align="center" valign="top" width="11%">
<a href="https://github.com/AlexXanderGrib/node-tdlib/issues/new">
<img
src="https://alexxandergrib.github.io/node-tdlib/icons/add.png"
width="75"
height="75"
alt=""
/><br />
Add your project
</a>
</td></tr></tbody></table>

## Credits

This package is based on [eilvelia/tdl](https://github.com/eilvelia/tdl)

Licenses:

- C++ addon - [MIT](./docs/licenses/addon.license.txt)
- Ci pipeline - [Blue Oak Model License 1.0.0](./docs/licenses/ci.license.md)

---
_Source: https://npm.io/package/tdlib-native · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._