Flutter plugin (Android)
Packaged as an Android FFI Flutter plugin with bundled native libraries.
← Back to Open SourceOpen Source / Flutter / TDLib
handy_tdlib_next
Maintained Flutter/Dart bindings for TDLib's libtdjson interface on Android — rooted in a production Follow Pay requirement.
What is handy_tdlib_next?
handy_tdlib_next is a community-maintained Flutter/Dart package providing bindings for Telegram's TDLib JSON interface (libtdjson). It is intended for Flutter applications that need to communicate with TDLib to build Telegram clients or integrate TDLib functionality.
The package exposes generated Dart models for TDLib functions and objects, FFI access to libtdjson through TdPlugin, and helpers to parse TDLib JSON into typed Dart objects. On Android, prebuilt libtdjson.so libraries are shipped with the plugin so consumers do not need to build TDLib themselves for that platform.
Why handy_tdlib_next exists
From production patch to public package
handy_tdlib_next did not start as a purely experimental package. It originated from a production problem while building Follow Pay: a Telegram-related verification flow that needed to stay inside the app rather than sending users outside.
Existing Flutter/Telegram libraries did not provide the reliability needed for that in-app flow. After researching handy_tdlib at the implementation level — how it bound Dart to TDLib/libtdjson — I developed a working patch/adaptation around it and used that patched implementation in Follow Pay production for approximately one year.
Later, noticing that developers were still downloading the original handy_tdlib package while needing a maintained Flutter TDLib integration, I published the maintained work as handy_tdlib_next. It is independently maintained under a new package name — a community-maintained fork lineage, not an official continuation of handy_tdlib, and not affiliated with Telegram, TDLib, Naji, or HandyGram.
Read the production origin story in the Follow Pay case study →
Engineering origin
- Production requirement
Follow Pay needed Telegram-related verification inside the app.
- Library evaluation
Multiple Flutter/Telegram options were tried; none reliably fit the required flow.
- handy_tdlib researched + patched
Deeper TDLib/libtdjson investigation led to a working adaptation.
- Production use (~1 year)
The patched implementation ran in Follow Pay before any public package release.
- Public maintenance
Continued demand around handy_tdlib motivated publishing a maintained package.
- handy_tdlib_next
Community-maintained Flutter TDLib integration on Android via Dart FFI.
Technical architecture
Requests flow from your Flutter app through typed Dart models and TdPlugin, across Dart FFI, into bundled libtdjson.so, and finally into TDLib.
- Flutter application
Your app drives TDLib client creation, requests, and updates.
- Dart API / TDLib models
Generated TdFunction and TdObject types plus JSON helpers.
- TdPlugin
Dart entrypoint for initialize, send, receive, and execute.
- Dart FFI
Foreign Function Interface bridging Dart to the native library.
- libtdjson.so
Bundled Android TDLib JSON client dynamic library.
- TDLib
Telegram Database Library v1.8.36 behind the JSON interface.
Technical details
Dart FFI wrapper
TdPlugin wraps libtdjson calls such as td_create_client_id, td_send, td_receive, and td_execute.
Generated TDLib API
Typed functions and objects generated from the TDLib scheme for a sealed Dart 3-friendly surface.
JSON helpers
convertJsonToObject and convertMapToObject parse TDLib JSON into typed TdObject values.
Custom library path
TdPlugin.initialize([String? libPath]) can load a non-default native library when needed.
Shipped Android ABIs
armeabi-v7a, arm64-v8a, x86, and x86_64 libtdjson.so builds are included.
Dart 3 / Flutter
Requires Dart SDK >=3.3.0 <4.0.0 and Flutter >=3.15.0.
TDLib 1.8.36
Bundled libtdjson corresponds to TDLib 1.8.36 as recorded in the package metadata.
Android SDK levels
minSdkVersion 21 and compileSdkVersion 34 in the plugin Android configuration.
Platform
Supported: Android
The package currently ships Android libtdjson.so libraries for armeabi-v7a, arm64-v8a, x86, and x86_64. Consumers do not need to build TDLib themselves for those ABIs.
iOS, Web, Windows, macOS, and Linux are not declared or supported by the current plugin configuration.
AndroidTDLib 1.8.36minSdk 21compileSdk 34Dart >=3.3.0 <4.0.0
Migrating from handy_tdlib
If your Flutter project previously depended on handy_tdlib, you can move to handy_tdlib_next by changing the package dependency and imports, then validating Android and TDLib behavior. handy_tdlib_next is independently maintained and is not presented as an official continuation of the original project.
- Replace the dependency: swap handy_tdlib for handy_tdlib_next in pubspec.yaml (for example handy_tdlib_next: ^2.3.13), then run flutter pub get.
- Update imports from package:handy_tdlib/... to package:handy_tdlib_next/... (for example handy_tdlib_next.dart, api.dart, client.dart).
- Review existing API usage before assuming drop-in compatibility — re-check TdPlugin usage, generated types, and JSON helpers against this package.
- Test Android startup and native library loading across your target ABIs.
- Test authentication, update handling, and isolate wiring (tdSend / tdReceive off the UI isolate where appropriate).
- Verify runtime behavior against the bundled TDLib 1.8.36 version.
Looking for an alternative to handy_tdlib?
If you have a Flutter project that previously depended on handy_tdlib and need a maintained package under a new package name, handy_tdlib_nextprovides Flutter/Dart bindings around TDLib's libtdjson interface for Android.
It is an independent community-maintained project and is not an official Telegram, TDLib, Naji, or HandyGram release.
FAQ
What is handy_tdlib_next?
handy_tdlib_next is a community-maintained Flutter/Dart package that provides bindings for Telegram's TDLib JSON interface (libtdjson), aimed at building Telegram clients or integrating TDLib features on Android.
Where did handy_tdlib_next come from?
It originated from a production Telegram verification requirement in Follow Pay. After evaluating existing Flutter/Telegram libraries, Abdul Moiz Dev investigated handy_tdlib, developed a working patch, used it in production for about a year, and later published the maintained work as handy_tdlib_next.
Is handy_tdlib_next a Flutter TDLib package?
Yes. It is a Flutter plugin with a Dart API that talks to TDLib through libtdjson using Dart FFI, including generated TDLib functions and objects.
Does handy_tdlib_next support Android?
Yes. Android is the supported plugin platform. The package ships prebuilt libtdjson.so libraries for common Android ABIs.
Which TDLib version does handy_tdlib_next use?
TDLib 1.8.36 (bundled libtdjson as documented in the package).
Does handy_tdlib_next use FFI?
Yes. TdPlugin uses Dart FFI to call into libtdjson.so for client creation, send, receive, and execute operations.
Can I migrate from handy_tdlib?
Yes, as a dependency and import rename to handy_tdlib_next, followed by careful API review and Android/TDLib regression testing. It is independently maintained and not presented as an official continuation of handy_tdlib.
Is handy_tdlib_next an official Telegram package?
No. It is an independent community package maintained by Abdul Moiz Dev. It is not an official Telegram or TDLib package, and it is not affiliated with, endorsed by, or maintained by Telegram, the TDLib project, Naji, or HandyGram unless those parties state otherwise.
Who maintains handy_tdlib_next?
Abdul Moiz Dev (@itxmoizdev).
Does it include libtdjson?
Yes for Android. Prebuilt libtdjson.so libraries are bundled under the plugin's jniLibs so consumers do not need to build TDLib themselves for supported Android ABIs.
Does it support iOS or Web?
No. The current plugin configuration declares Android only. iOS, Web, Windows, macOS, and Linux are not declared or supported in this package.
Links
Maintained by Abdul Moiz Dev (@itxmoizdev).