iMessage SMS bridge setup (Android)

In addition to being an iMessage bridge, mautrix-imessage can run on Android to bridge SMS messages from your phone. The Android SMS bridge works similar to the jailbroken iOS setup, but instead of Brooklyn, the wrapper app for the bridge is android-sms.

Requirements

  • An Android device with Android 5 or higher.
    • N.B. You must set the android-sms app as your default SMS app. Being the default SMS app is no longer required.
  • A Matrix homeserver that supports application services (e.g. Synapse). You need access to register an appservice, which usually involves editing the homeserver config file.
  • A websocket proxy to receive appservice transactions. If you want end-to-bridge encryption, the sync proxy component (mentioned in the websocket proxy readme) is also recommended to minimize battery usage.

Installation

Compiling manually

  1. Install the latest Android SDK and NDK version 21.3.6528147.
  2. Clone the android-sms repo. Use --recursive when cloning or git submodule init && git submodule update after cloning to ensure that the mautrix-imessage submodule is present.
  3. Run ./mautrix.sh to compile mautrix-imessage for Android.
  4. Put your config.yaml in app/src/main/assets/ (create the directory if it doesn't exist).
  5. Run ./gradlew installDebug to compile the app and install it over ADB.

Precompiled builds

There are currently no precompiled versions available, as the config must be bundled at compile time. Support for setting up with QR code similar to the iOS setup will be added soon, and precompiled APKs will be available in the GitLab CI after that.

Configuring and running

  1. Get the example config and fill it out. You'll at least need to:
    • Fill everything in the homeserver section.
    • Set bridge -> user to your MXID.
    • Change imessage -> platform to android.
    • Generate random tokens for the as_token and hs_token fields.
    • The database and log directory paths must be absolute paths in the /data/user/0/com.beeper.sms.app directory.
  2. Get the example registration and copy the relevant values from the config.
  3. Set up mautrix-wsproxy (and the sync proxy).
  4. Add the path to the registration file to your Synapse homeserver.yaml under app_service_config_files, then restart Synapse.
  5. Build and run the android-sms app with your config.
  6. Open the app and grant it SMS permissions to start the bridge.