README.md

May 8, 2026 · View on GitHub

react-native-tdlib

The fastest way to build a real Telegram client in React Native.
TDLib under the hood, prebuilt binaries, one API on iOS and Android. Listed in the official TDLib documentation under JavaScript wrappers.

Website → · Docs · Example app · npm

_{↑ The example app shipped in example/. npm install, run, log in.}

Why

Building a Telegram client should not start with an hour-long TDLib compile. This library ships prebuilt TDLib binaries for iOS (xcframework, device + simulator) and Android (arm64-v8a, armeabi-v7a, x86_64), wraps the whole API in a single RN module, and streams every update to JS through NativeEventEmitter.

🚀 53 first-class methods — auth, chats, messages, reactions, files, options, users.
🔄 Real-time updates — new messages, typing, read receipts, download progress, reactions.
🧩 Cross-platform parity — iOS and Android emit the same TDLib JSON shape. Write once.
🟦 Fully typed — .d.ts covers every method, event and result.
📦 Zero native setup — no cmake, no brew install. pod install and go.
🎬 Ships with a Telegram-like example app — auth wizard, chat list, message view, reactions, reply, typing.

Install

npm install react-native-tdlib
cd ios && pod install

Requires React Native ≥ 0.60 (autolinking), iOS ≥ 11, Android minSdk ≥ 21.

Hello, Telegram

import TdLib from 'react-native-tdlib';
import {NativeEventEmitter, NativeModules} from 'react-native';

const emitter = new NativeEventEmitter(NativeModules.TdLibModule);

// 1) Start TDLib
await TdLib.startTdLib({api_id: 12345, api_hash: 'your_hash'});

// 2) Listen for everything
emitter.addListener('tdlib-update', e => {
  if (e.type === 'updateNewMessage') {
    console.log('📨', JSON.parse(e.raw).message);
  }
});

// 3) Log in (drive via updateAuthorizationState — see docs)
await TdLib.login({countrycode: '+1', phoneNumber: '5551234567'});
await TdLib.verifyPhoneNumber('12345');

// 4) Load chats, send a message
await TdLib.loadChats(25);
const chats = JSON.parse(await TdLib.getChats(25));
await TdLib.sendMessage(chats[0].id, 'Hello from React Native!');

Example app

A full Telegram-like reference client ships under example/: login wizard, chat list with live updates, chat view with reactions, reply, typing indicator, photo previews, pagination.

git clone https://github.com/vladlenskiy/react-native-tdlib.git
cd react-native-tdlib/example && npm install
cd ios && pod install && cd ..
# Provide your TDLib api_id / api_hash from https://my.telegram.org/apps:
cp .env.example .env
$EDITOR .env
npx react-native run-ios       # or run-android

Used by

Apps and projects shipping react-native-tdlib:

Using react-native-tdlib in production? Open a PR adding your project here, or list yours via the GitHub dependents view.

Documentation

Getting Started → — install, auth flow, first chat.
API Reference → — all 53 methods, grouped.
Cookbook → — practical recipes (messages, reactions, files, options, typing).
Events → — tdlib-update stream, update types cheatsheet.
Platform Parity → — how iOS and Android stay in sync.