Note: This guide is now archived since the BlueBubbles bridge has merged into the main BBCTL branch. Please see https://rentry.org/beeper_bluebubbles_bridge for updated guide

Mautrix/iMessage BlueBubbles Connector with Beeper

In-depth noob guide

Written by @ampersandru Transcribed to rentry by @shadowdrake:beeper.com Last updated 2/9/2024

The Guide

In SSH/Terminal (a sudo command may ask for a password, use your mac's login password):

1. Install Homebrew:
   /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
2. After Homebrew is installed (see prereq above):
   brew install go libolm libheif pkg-config pre-commit
3. Add bbctl download location to $PATH:
   - Method 1:
   sudo cp /[path-to-bbctl-folder]/bbctl/bbctl-macos-amd64 /usr/local/bin/
   RESTART YOUR TERMINAL SESSION
   - Method 2:
   sudo nano /etc/paths
   Add a new line with the location of where you downloaded bbctl (i.e., /Users/Shared/Downloads/bbctldownloadfolder/), save and exit.
   RESTART YOUR TERMINAL SESSION
4. Change directory to the location of where you installed bbctl (i.e. cd /Users/Shared/Downloads/bbctldownloadfolder/)
5. chmod +x bbctl-macos-amd64
6. bbctl-macos-amd64 login and login to your Beeper account using the email you used
7. cd && git clone https://github.com/mautrix/imessage.git && cd imessage && pre-commit install && git checkout bluebubbles
8. Replace with your BB URL for bluebubbles_url and your BB password for bluebubles_password . Ensure you keep the apostrophes (') around 'bluebubbles_url=http://localhost:1234' and 'bluebubbles_password=BluEBuBblESPa$$word':
   bbctl-macos-amd64 run --local-dev --param 'bluebubbles_url=http://localhost:1234' --param 'bluebubbles_password=BluEBuBblESPa$$word' --param 'imessage_platform=bluebubbles' sh-imessage

The bridge should then start automatically backfill past conversations and may take a bit to complete. If you start seeing "DBG Received ping from BlueBubbles websocket component=bluebubbles" then you should be all set. You will either have to start NEW iMessage conversations with the BlueBubbles app or use the bot commands below. You must either leave this terminal window open, use TMUX, or follow the automating startup guides

Automating Startup

As mentioned above, you must leave this bridge runnning. If you restart your machine, you will have to run the command from step 7 again. Or you can use one of the following methods to have it automatically run each time you boot up.

• Using launchd
  • Follow this guide by @shadowdrake:beeper.com:
    https://rentry.org/bb2hcep6
• Using cron
  • Follow this guide by David
    https://rentry.org/bb-cron

Advanced Features, Settings, & Options

The following are all optional.

Updating the bridge

1. ctrl+c to stop the bridge
2. git fetch && git pull
3. bbctl-macos-amd64 run --local-dev --param 'bluebubbles_url=http://localhost:1234' --param 'bluebubbles_password=BluEBuBblESPa$$word' --param 'imessage_platform=bluebubbles' sh-imessage

Beeper Bot Commands

You are able to search for BlueBubbles contacts and start new iMessage conversations with them using the Beeper bridge bot

1. Start a new chat within Beeper with @sh-imessagebot:beeper.local
2. search-contacts NAME/EMAIL/PHONE to search for contacts
3. pm PHONE/EMAIL to start a iMessage conversation. Phone numbers should have country code and number (i.e., +14206969696) The bot will respond with a room where you can tap to open and send a message.
4. You can pin or favorite this bot for later usage.

Backfill Options

If you want to modify the default backfill options, ctrl+c to stop the bridge, open config.yaml within the imessage folder with your favorite editor and find these lines. If you are getting permission errors, you can either copy config.yaml to another folder, edit it and then drag it back or in terminal do sudo nano config.yaml

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

backfill:
    # Should backfilling be enabled at all?
    enable: true
    # Maximum number of messages to backfill for new portal rooms.
    initial_limit: 100
    # Maximum age of chats to sync in days.
    initial_sync_max_age: 0.5
    # If a backfilled chat is older than this number of hours, mark it as read even if it's unread on iMessage.
    # Set to -1 to let any chat be unread.
    unread_hours_threshold: 720

Fixing Contact Names and Contact Pictures

By default, the desktop Windows and macOS Beeper apps will show the correct Contact name but no large contact picture. The Android Beeper app will show the correct, large contact picture but will append "& iMessage" at the end of the contact names. Only the iOS Beeper app will show the correct, large contact picture and the correct contact name without "& iMessage". There is a way to correct this but requires some finesse and is completely optional. Props to matchstick for figuring this out and testing it.

1. ctrl+c to stop the bridge, if currently running
2. bbctl-macos-amd64 delete sh-imessage
3. Open Finder, at the top, click "Go", click "Home" and then delete the imessage folder (this is the bridge folder)
4. cd && git clone https://github.com/mautrix/imessage.git && cd imessage && pre-commit install && git checkout bluebubbles
5. Run the bbctl run command and once you see compiling for libheif (will happen almost right away) hit ctrl+c to end the bridge. bbctl-macos-amd64 run --local-dev --param 'bluebubbles_url=http://localhost:1234' --param 'bluebubbles_password=BluEBuBblESPa$$word' --param 'imessage_platform=bluebubbles' sh-imessage
6. Open config.yaml within the imessage folder with your favorite editor. If you are getting permission errors, you can either copy config.yaml to another folder, edit it and then drag it back or in terminal do sudo nano config.yaml
7. Find private_chat_portal_meta in config.yaml and change it from false to auto and save the file. If you want to change backfill options, you should do that now.
8. Run bbctl run again and your contact names and photos should be all correct. bbctl-macos-amd64 run --local-dev --param 'bluebubbles_url=http://localhost:1234' --param 'bluebubbles_password=BluEBuBblESPa$$word' --param 'imessage_platform=bluebubbles' sh-imessage

Starting fresh/Deleting everything

If you are having errors or issues with the bridge, need to update your BB url or password, the easiest way is to start fresh and reinstall it. Because this bridge backfills chats, you don't really lose anything.

1. ctrl+c to stop the bridge, if currently running
2. bbctl-macos-amd64 delete sh-imessage
3. Open Finder, at the top, click "Go", click "Home" and then delete the imessage folder (this is the bridge folder)
4. Start the commands from step 7, above, in SSH/Terminal

Questions, Issues, or Requests?

1. In the Beeper Desktop App, click the Settings Gear (Cog) at the top, Join Matrix Room, near the top-ish right, click the drop-down and "Add new server"
2. Add a server: maunium.net
3. Find the iMessage Room: #imessage:maunium.net

Donate!

None of this would be possible without the recent hard work of Donovon Simpson and Christian Nuss, which built upon the foundational work of Tulir (creator of mautrix-imessage and Beeper Lead Architect) and the BlueBubbles team who supported this project, along with many community members who tested and reported their findings. To acknowledge and support these incredible folks and their continued efforts, you can donate at the following links:

• Tulir: https://github.com/sponsors/tulir
• Donovon Simpson: https://www.buymeacoffee.com/trek.boldly.go or https://github.com/sponsors/trek-boldly-go
• BlueBubbles Team: https://bluebubbles.app/donate
• Christian Nuss: https://github.com/cnuss (awaiting sponsor link)