Mautrix/iMessage BlueBubbles Connector with Beeper

In-depth noob guide

Written by @ampersandru + @matchstick Last updated 2/13/2024

The Guide (Automated)

Use the script created by @matchstick to automate the entire install process:
https://github.com/ngencokamin/sh-imessage-setup

The Guide (Manual)

SSH into your Mac or open a new terminal window, then run the following:

1. Navigate to your downloads folder with cd Downloads
2. Run chmod +x bbctl-<your version> (you can type chmod +x bbctl and then press tab to autofill the filename)
3. Run sudo mv bbctl-<your version> /usr/local/bin/bbctl (a sudo command may ask for a password, use your mac's login password)
4. Run bbctl login and follow the prompts to log into your Beeper account
5. Replace with your BB URL for bluebubbles_url (recommend to leave it as localhost:1234) and your BB password for bluebubles_password . Ensure you keep the apostrophes (') around 'bluebubbles_url=http://localhost:1234' and 'bluebubbles_password=YOUR_PASSWORD':
   
   ⎗

   ✓

   1	bbctl run --param 'bluebubbles_url=http://localhost:1234' --param 'bluebubbles_password=YOUR_PASSWORD' --param 'imessage_platform=bluebubbles' sh-imessage

The bridge should then start automatically backfilling your iMessage conversations from the past 7 days. This step 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 may see a popup to give bbctl full disk access. Say Yes and check if it has access in macOS Security & Privacy settings otherwise your bridge may not fully work.

You must either leave this terminal window open, use TMUX, or follow the automating startup guides

Note: iMessages will not have its own chat/service category in Beeper - they will just show up in the inbox. Unforunately, this is how self-hosted bridges work with Beeper.

Starting New Conversations with Contacts

Unfortunately, self-hosted bridges do not have integration with Beeper to start new conversations within their app, easily. You have the following options to do this if backfill did not sync a previous conversation or you want to start a new conversation with someone:

1. Use the BlueBubbles App to start a new conversation - This new conversation will sync to Beeper
2. (If you have your phone number linked to iMessage) Send a SMS within the Beeper app. When they respond, it should go to iMessage instead and show up in Beeper
3. Use the Bridge Bot Commands

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 5 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

Optional Features, Settings, & Options

The following are all optional.

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 from the default 7 days, ctrl+c to stop the bridge, open /Users/USERNAME/Library/Application Support/bbctl/prod/sh-imessage/config.yaml 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 within that directory

 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: 7
    # 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

You must update your bridge command to include --no-override-config otherwise it will overwrite your backfill update:

1

bbctl run --no-override-config --param 'bluebubbles_url=http://localhost:1234' --param 'bluebubbles_password=YOUR_PASSWORD' --param 'imessage_platform=bluebubbles' sh-imessage

Increasing Max Attachment Limit

If you want to modify the default attachment limit from the default 50mb, ctrl+c to stop the bridge, open /Users/USERNAME/Library/Application Support/bbctl/prod/sh-imessage/config.yaml with your favorite editor and find these lines. Update imessage_min_size to whatever you want, in bytes. 1024288000 in the example below is about 975mb. BlueBubbles has a limit of 1gb itself. If you do not change from the default 50mb, anything larger than 50mb (usually videos) will upload to Beeper servers and send the other person a link to the uploaded file.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

media_viewer:
    # The address to the media viewer. If null, media viewer links will not be used.
    url: https://media.beeper.com
    # The homeserver domain to pass to the media viewer to use for downloading media.
    # If null, will use the server name configured in the homeserver section.
    homeserver: beeper.com
    # The minimum number of bytes in a file before the bridge switches to using the media viewer when sending MMS.
    # Note that for unencrypted files, this will use a direct link to the homeserver rather than the media viewer.
    sms_min_size: 409600
    # Same as above, but for iMessages.
    imessage_min_size: 1024288000
    # Template text when inserting media viewer URLs.
    # %s is replaced with the actual URL.
    template: "Full size attachment: %s"

You must update your bridge command to include --no-override-config otherwise it will overwrite your attachment limit update:

1

bbctl run --no-override-config --param 'bluebubbles_url=http://localhost:1234' --param 'bluebubbles_password=YOUR_PASSWORD' --param 'imessage_platform=bluebubbles' sh-imessage

Custom Startup Command

To add a custom startup command that does not require you re-write your parameters each time, run the following commands

1. echo alias start-bb-server=\"<your startup command>\" >> ~/.zshrc (note: you must include the \ before each double quote in the command). Example syntax:
   
   ⎗

   ✓

   1	echo alias start-bb-server=\"bbctl run --param 'bluebubbles_url=http://localhost:1234' --param 'bluebubbles_password=PASSWORD' --param 'imessage_platform=bluebubbles' sh-imessage\" >> ~/.zshrc

2. source ~/.zshrc
3. You should now be able to start your server using the command start-bb-server in your 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)