Read this in other languages: Русский, Türkçe, 한국어, اُردو, Español

MonoGram is a modern, lightning-fast, and elegant unofficial Telegram client for Android. Built with Jetpack Compose and Material Design 3, it delivers a native and fluid experience powered by the official TDLib.

Support the project on Boosty.

• Independent Client — Not a fork of Telegram for Android. MonoGram is built entirely from scratch as a standalone project.
• Material Design 3 — A beautiful, adaptive UI that looks great on phones, tablets, and foldables.
• Secure — Built-in biometric locking and encrypted local storage.
• Media Rich — High-performance media playback with ExoPlayer and Coil 3.
• Fast & Efficient — Powered by Kotlin Coroutines and optimized for performance.
• Clean Architecture — Clear separation of concerns with Domain, Data, and Presentation layers.
• MVI Pattern — Predictable state management using MVIKotlin.
• No NFT or Crypto — MonoGram will never include NFT promotions, gifts or any other features pushed by Telegram that we consider outside the scope of a messaging app.

Follow these steps to set up the project locally.

• Android Studio: Ladybug or newer (recommended).
• JDK: Java 17 or newer.

git clone --recurse-submodules https://github.com/monogram-android/monogram.git
cd monogram

To connect to Telegram servers, you need your own API credentials.

1. Log in to my.telegram.org.
2. Go to API development tools.
3. Create a new application to get your App api_id and App api_hash.
4. Create a file named local.properties in the root directory of the project (if it doesn't exist).
5. Add the following lines:

API_ID=12345678
API_HASH=your_api_hash_here

For signed release builds from Gradle, add these properties too:

RELEASE_STORE_FILE=keystore/release.jks
RELEASE_STORE_PASSWORD=your_store_password
RELEASE_KEY_ALIAS=your_key_alias
RELEASE_KEY_PASSWORD=your_key_password

This step is required for firebase build variants. You can skip it if you only plan to build libre variants.

1. Log in to the Firebase console.

2. Create a new project.

3. Add two Firebase Android apps:

   • org.monogram for release builds
   • org.monogram.debug for debug builds

4. Download the google-services.json file and copy it to the root of the app module ( monogram/app/google-services.json). Make sure it contains clients for both package names above.

5. Go to the Cloud Messaging section.

6. Click Manage service accounts.

7. Select the Keys section at the top of the window that opens.

8. Click Add key and select the JSON option. Wait for the file to download.

9. Return to the Telegram API page where you received your App ID.

10. Click Update next to the FCM credentials section.

11. Upload the service account JSON on the page that opens.

The animations require libvpx to be compiled. This has to be done before starting a Gradle build or it will cause build failures.

1. Change your working directory to presentation/src/main/cpp
2. In build.sh, add your ANDROID_NDK_HOME
3. Run build.sh and wait for it to finish

1. Open the project in Android Studio.
2. Increase the IDE indexing limits so TdApi.java (the TDLib wrapper) is indexed correctly. In Android Studio or IntelliJ IDEA, open Help → Edit Custom Properties..., paste the lines below, and restart the IDE if prompted:

# size in Kb
idea.max.intellisense.filesize=20480
# size in Kb
idea.max.content.load.filesize=20480

3. Sync Gradle.
4. Select the app run configuration.
5. Connect a device or start an emulator.
6. Click Run.

If you need to build TDLib from source, first install the required dependencies. For Debian/Ubuntu-based distributions:

sudo apt-get update
sudo apt-get install build-essential git curl wget php perl gperf unzip zip default-jdk cmake

Then run the build script from the root of your project:

./build-tdlib.sh

The script supports:

• ./build-tdlib.sh official
• ./build-tdlib.sh telemt
• ./build-tdlib.sh both

Upstream repositories used by the script:

• official: tdlib/td
• telemt: telemt/tdlib-obf

If you run ./build-tdlib.sh without arguments, it will prompt you to choose one of these modes interactively.

Use these variants in Android Studio:

• officialFirebaseDebug
• officialFirebaseRelease
• officialLibreDebug
• officialLibreRelease
• telemtFirebaseDebug
• telemtFirebaseRelease
• telemtLibreDebug
• telemtLibreRelease

Variant naming:

• official / telemt selects the TDLib source
• firebase enables FCM / Firebase-backed push setup
• libre builds without Firebase dependencies

Useful Gradle tasks:

./gradlew :app:assembleOfficialFirebaseRelease
./gradlew :app:assembleTelemtFirebaseRelease
./gradlew :app:assembleOfficialFirebaseDebug
./gradlew :app:assembleTelemtFirebaseDebug
./gradlew :app:assembleOfficialLibreRelease
./gradlew :app:assembleTelemtLibreRelease
./gradlew :app:assembleOfficialLibreDebug
./gradlew :app:assembleTelemtLibreDebug

APK names:

• official Firebase: monogram-arm64-v8a-<version>-release.apk
• official libre: monogram-libre-arm64-v8a-<version>-release.apk
• Telemt Firebase: monogram-telemt-arm64-v8a-<version>-release.apk
• Telemt libre: monogram-telemt-libre-arm64-v8a-<version>-release.apk

We welcome contributions! Whether it's fixing bugs, improving documentation, or suggesting new features.

1. Check the Issues — Look for open issues or create a new one to discuss your ideas.
2. Work from develop — Create your branch from develop and keep your work based on that branch.
3. Fork & Branch — Fork the repo and create a feature branch.
4. Code Style — Follow the existing Kotlin coding style and Clean Architecture guidelines.
5. Submit a PR — Open a Pull Request to develop with a clear description of your changes.

• Bugs — Open an issue and use the [Bug] tag in the title (e.g. [Bug] App crashes on startup). You can also browse all known bugs on the Bug Tracker.
• Feature Requests — Open an issue with the [Feature] tag (e.g. [Feature] Support scheduled messages). Existing feature requests can be found on the Feature Board.

MonoGram welcomes community translations! You can contribute your own language by editing the strings resource file.

The source strings are located at presentation/src/main/res/values/string.xml. To add a new language, create a corresponding values-<locale>/string.xml file (e.g. values-de/string.xml for German) and translate the strings there. Open a PR with your translation and we'll get it merged.

MonoGram leverages the latest Android development tools and libraries:

The project follows a multi-module structure to ensure separation of concerns and scalability:

This project is licensed under the GNU General Public License v3.0.