explaingit

tdlib/td

★ 8,763C++Audience · developerComplexity · 4/5LicenseSetup · hard

TLDR

TDLib is a cross-platform C++ library that handles all the low-level Telegram networking, encryption, and local storage so you can build Telegram clients or bots in virtually any programming language.

Mindmap

mindmap
  root((TDLib))
    What it does
      Telegram networking
      Encryption storage
      Async API
    Language support
      JSON C interface
      Java JNI bindings
      .NET bindings
    Platforms
      Android iOS Windows
      macOS Linux
      WebAssembly
    Building
      C++17 compiler
      CMake and OpenSSL
      Online build guide
Click or tap to explore — scroll the page freely

Code map

Detail Auto

An interactive map of this repo's files and how they connect — its source is parsed live in your browser. Click Visualize to build it.

filefunction / class

Things people build with this

USE CASE 1

Build a custom Telegram client for desktop, mobile, or web that connects to Telegram's servers without implementing the protocol yourself.

USE CASE 2

Create a Telegram bot in Python or JavaScript by calling TDLib's JSON API from your preferred language.

USE CASE 3

Integrate Telegram messaging into an existing business application using TDLib as the low-level engine.

USE CASE 4

Run a bot management service that handles thousands of concurrent bots inside a single TDLib instance.

Tech stack

C++OpenSSLCMakeJSONWebAssembly

Getting it running

Difficulty · hard Time to first run · 1day+

Requires building from source with a C++17 compiler, CMake, OpenSSL, zlib, and gperf, setup is non-trivial even with the online build guide.

Boost Software License, use freely for any purpose including commercial projects, with very minimal restrictions.

In plain English

TDLib, short for Telegram Database library, is a C++ library that handles the low-level work of connecting to Telegram. If you want to build your own Telegram client app or bot, TDLib takes care of the network connection, message encryption, and storing chat data locally, so you do not have to implement those details yourself. Although the library is written in C++, it is designed to be called from almost any programming language. It exposes a JSON interface based on a simple C function, which means you can drive it from Python, Go, JavaScript, or anything else that can call C functions. For Java and .NET projects, native bindings are available through JNI and C++/CLI respectively, avoiding the need to go through JSON. All API requests are fully asynchronous, so calls to TDLib do not block each other. The library runs on a wide range of platforms: Android, iOS, Windows, macOS, Linux, FreeBSD, WebAssembly, watchOS, tvOS, Tizen, and others. All locally stored data is encrypted with a key you supply. The library is also used internally by Telegram for their Bot API server, where a single instance handles more than 37,000 active bots at the same time. Building TDLib requires a C++17 compiler, OpenSSL, zlib, CMake, and gperf. The project provides an online build instructions generator where you select your target language and operating system and receive a step-by-step build guide. Examples for C++, Java, and C# are included in the repository. The API follows semantic versioning, so libraries built against one minor version remain binary compatible with others sharing the same major version number.

Copy-paste prompts

Prompt 1
Show me how to connect to TDLib from Python using its JSON interface, authenticate with a phone number, and print the list of recent chats.
Prompt 2
I want to build a Telegram bot using TDLib that receives messages and replies automatically. How do I set up the event loop and handle incoming update objects?
Prompt 3
How do I build TDLib from source on Ubuntu 22.04 and then call it from a Node.js application?
Prompt 4
Explain how TDLib's asynchronous request-response model works, how do I send a request and match it to the response that comes back later?
Prompt 5
I want to run TDLib in a Docker container and expose it as a JSON API service. Show me how to structure the setup.
Open on GitHub → Explain another repo

← tdlib on gitmyhub — every repo by this author, as a profile.

Verify against the repo before relying on details.