Build TDLib and Make the First Connection

Decide first: build it, or use what exists

TDLib is open-source C++, and normally you build it yourself on your own machine. The route depends on the language you write in.

The exact commands for each platform and language come from the build instructions generator linked from the official TDLib page (core.telegram.org/tdlib). Pick your operating system and language and it prints commands you can paste. This article covers what to know before and after. Whether you need TDLib at all is in the four Telegram APIs.

Tools you need

On Windows the usual way is to install OpenSSL, zlib and gperf with the vcpkg package manager and point CMake at them. Choosing Windows in the generator turns this into commands.

The Windows build, as we actually ran it

These are the steps the generator gives for Windows, x64 and JSON, exactly as we ran them. The commands are for PowerShell, and vcpkg is pinned to the version the generator specifies.

git clone https://github.com/tdlib/td.git
cd td
git clone https://github.com/Microsoft/vcpkg.git
cd vcpkg
git checkout <the pinned commit the generator shows>
./bootstrap-vcpkg.bat
./vcpkg.exe install gperf:x64-windows openssl:x64-windows zlib:x64-windows
cd ..
mkdir build
cd build
cmake -A x64 -DCMAKE_INSTALL_PREFIX:PATH=../tdlib -DCMAKE_TOOLCHAIN_FILE:FILEPATH=../vcpkg/scripts/buildsystems/vcpkg.cmake ..
cmake --build . --target install --config Release

We measured on a virtual PC with Windows 11, 8 CPUs and 12 GB of memory, adding --parallel 4 to the last command to keep memory use down. Times depend on your hardware.

• On its first run, vcpkg downloads the tools it needs, PowerShell 7 and 7-Zip, by itself.
• gperf's source comes from the GNU servers, which can time out on some networks; it happened to us once. Download the same file from another GNU mirror into vcpkg's downloads folder and run again. vcpkg checks the content by hash, so a different mirror is safe.
• When the build finishes, tdlib/bin contains tdjson.dll plus OpenSSL (libcrypto-3-x64.dll, libssl-3-x64.dll) and zlib1.dll. Ship all four files with your program.

The first connection: what success looks like

Load tdjson in your program, create a TDLib client and start the receive loop. If the first updates include the TDLib version (the version option) and the authorization state "waiting for parameters" (authorizationStateWaitTdlibParameters), the connection works. In our test both arrived immediately, without logging in.

Next, send setTdlibParameters with your api_id, api_hash and a data folder, and TDLib moves on to the login steps; see getting an api_id and the user login flow. While developing, turn on use_test_dc to run against the test servers with a test account instead of a real one.

Every available method is listed in TDLib's schema file, td_api.tl; see reading the TL schema and layers.