imessage-options.md

iMessage Options

Disclaimers

1. Note that only the BlueBubbles method works if you want to integrate with Beeper. Technically there are other self-hosted iMessage bridges, but BlueBubbles connector is by far the least janky and most reliable option.
2. While BlueBubbles can theoretically run in a VM or Docker container (see Docker-OSX section for more info), you MUST use real Apple hardware for OpenBubbles.
3. I'm not including anything about OpenBubbles' upcoming paid hosting options in this guide. They aren't out yet, and I know very little about how it'll work.
4. For BlueBubbles, the version of MacOS matters. I recommend Ventura, as it has the best combination of features and compatability. If your Mac is too old, check out OCLP. It's what I used to get Ventura running on a 2012 Mac Mini, and it works great.
5. Neither of these methods (using Macs) will register your phone number, and your iMessage will be tied to your email only. You can get around this if you have an old iPhone and 50¢ to spare (see Registering Phone Number).
6. These methods are not mutually exclusive! You can set both up to access features from both, or to have one act as a backup. That's what I do, personally.

Method 1: BlueBubbles

Pros and Cons

Pros	Cons
Can be connected to Beeper.	Computer must be always on (regardless of if you use the Beeper Bridge).
Can be run in a VM or Docker container.	Many features + improved send and receive require SIP be disabled on the host Mac (See here for a full list).
Since BlueBubbles just taps into the messages app on the Mac, there are less concerns about Apply shutting it down + it's pretty much undetectable afaik.	Inherently slightly slower than OpenBubbles (not to the point where it's been unusable in my experience, but worth noting).
Super thorough documentation with a larger community base and dedicated Discord.	Missing features compared to OpenBubbles.
Syncs iMessage history.	Less active development (dev just had a baby, so major congrats).
Fully functional desktop and web apps.

Installation of BlueBubbles

Option 1: Real Hardware

1. (optional) Upgrade your Mac to Ventura if it isn't already. If your Mac does not officially support upgrading to Ventura or higher, you can check out OCLP (Opencore Legacy Patcher) here to see how you can upgrade. Do note that upgrading with OCLP and then changing hardware can cause issues with iMessage. If you have trouble sending and receiving iMessages after an upgrade and hardware change, check out this guide to try and resolve it.
2. Follow this guide for the initial BlueBubbles setup process.
3. (optional, but recommended) Follow this guide to disable SIP and enable Private API features.

Option 2: Docker OSX (a little more advanced)

1. Follow this guide to go through the setup process. MAKE SURE TO READ THE WHOLE THING FIRST.

Next steps

1. Check out the following section to connect to BlueBubbles to Beeper.
2. Check out Registering Phone Number if you have a spare iPhone and want iMessage to not just use your email. This does NOT require Jailbreak.

Beeper Bridge Setup

Option 1: Automated Setup

1. Navigate to this repository.
2. Follow the steps under "Prerequisites".
   1. Open up a terminal
   2. Paste in /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" and press enter to install Homebrew. If prompted for a password, enter your user password. Note that the input will not be visible, I promise it's still working.
   3. Paste in xcode-select --install and press enter to install XCode command line tools
   4. You already completed the last step in the previous section, just make sure the BlueBubbles app is running.
   5. (optional) Run brew install tmux to install a utility called tmux. It is optional, but does provide additional benefits in running the bridge later on.
3. Open a terminal window.
4. Paste git clone https://github.com/ngencokamin/sh-imessage-setup.git into the window and press enter to download the code.
5. In the same terminal window, run cd sh-imessage-setup to navigate into the newly downloaded folder.
6. Run chmod +x setup.sh && ./setup.sh to give the script permissions and run it.
7. Follow the prompts until the script is done. If you're not sure about something, feel free to reach out and ask. For most things, you will use defaults NOTE: The option to create a cron job to auto launch the bridge if it fails or the computer restarts does NOT function correctly. If anyone wants to help me test a new approach with launchd, I'd be happy to continue work on that

Option 2: Manual Setup

1. Navigate to this page and download the correct version for your Mac. You want bbctl-macos-arm64 if you have an M series Mac, otherwise bbctl-macos-amd64.
2. Open a new terminal window.
3. Navigate to your downloads folder by running cd Downloads.
   1. Run the command mv bbctl-<your-version> bbctl to rename the downloaded file (replace <your-version> with either macos-arm64 or macos-amd64 depending on which version you downloaded).
4. Run chmod +x bbctl to make the file executable
5. Run sudo mkdir -p /usr/local/bin && [[ $PATH == *":/usr/local/bin:"* ]] || echo 'export PATH="$PATH:/usr/local/bin"' >> $HOME/.$(basename "$SHELL")rc && source $HOME/.$(basename $SHELL)rc to create a local executables folder and add it to PATH (a sudo command may ask for a password, use your mac's login password). What this command does exactly:
   1. sudo mkdir -p /usr/local/bin recursively create a folder called /usr/local/bin if it doesn't exist. Some newer versions of Mac OS no longer include this folder, which is why we are creating it.
   2. && means do the next command if the first one completed successfully.
   3. [[ $PATH == *":/usr/local/bin:"* ]] checks if the $PATH variable contains this folder already. $PATH variable tells your computer where to look for programs when you type a command.
   4. || means or. In this case, we are saying to run the commands after the previous statement if the previous statement is false (ie it is not in path).
   5. echo 'export PATH="$PATH:/usr/local/bin"' >> $HOME/.$(basename "$SHELL")rc is appending the command saying to look for /usr/local/bin in path to the configuration file of the current terminal shell.
   6. source $HOME/.$(basename $SHELL)rc is saying to apply changes to the current window, rather than requiring a new window be opened to take effect.
6. Run sudo mv bbctl /usr/local/bin/bbctl to move the file into PATH
7. Run bbctl login and follow the prompts to log into your Beeper account
8. Run the following command after replacing the following
   1. "http://localhost:1234" should be replaced with your BlueBubbles URL ONLY IF YOU SPECIFICALLY SET ONE. If you're not sure, this probably doesn't apply to you.
   2. Replace YOUR_PASSWORD with the password you set for your BlueBubbles server while setting up the app.

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

Automatic LPotential paid hosting options in the future, including phone number without extra steps.aunch

1. Follow this guide to set up Auto Launching manually.
2. If you used the automated setup script and are down to help test something, hit me up at @matchstick:beeper.com about helping me fix auto launch in the script.

Method 2: OpenBubbles

Pros and Cons

Pros	Cons
More features (mostly functional facetime, find my, emoji reactions, etc).	Requires a real Mac. SERIOUSLY, DO NOT USE THIS WITH A VM OR DOCKER!
Slightly faster send and receive, especially with pictures.	Potentially more detectable than BlueBubbles if Apple figures out how it works and cares enough to shut it down.
Does not require Mac always be on.	Can have slowdowns in the app (at least in my experience, though it's really not bad. Just the occasionally momentary freeze).
Much more active development.	Does not sync message history, can only get old messages from an OpenBubbles backup.
Potential paid hosting options in the future, including phone number without extra steps.	Desktop apps.... technically exist for Windows and Linux, but they don't support contacts at all, with no plans to include this function. Also, I can't get the flatpak to register at all at the moment.
Works with a Jailbroken iPhone if you don't have a Mac (though it is very much not recommended by the dev).	Cannot be connected to Beeper.
One Mac can be used to authenticate for multiple users (but don't share your code online, no more than 20 users should have the same code at a time).
Incredibly easy setup with no need to disable SIP or mess around in the terminal.
Does not require Mac be logged into your Apple ID/is not tied to Mac Apple ID (so you can use someone else's Mac, or share your code as mentioned above).

Mac Setup

1. Just follow this guide. It'll take 5 minutes and requires 0 technical knowledge. Just download the app on Mac, run it, and scan the QR code in the OpenBubbles app. Seriously, it's so easy.
2. Continue to Registering Phone Number for more info if you want to connect your phone number.

Paid Hosting

1. Join the waitlist.
2. Wait Notes:

• Paid hosting includes phone number registration.
• This service is currently live in a limited capacity. You still need to join the waitlist. Check the OpenBubbles Discord server for help or more information.
• I'll update once I get concrete confirmation, but from what I can tell the monthly cost is $10.

Registering Phone Number

So there are four real options here, all but one requiring an iPhone. It should be noted that only the 1st method works for BlueBubbles/Beeper, so if you want the bridge that's your only option. Also, these all require your iPhone to remain on and connected to wifi*.

All Devices

AirMessage Tricks/Sim Swap

Requires an active and inactive sim card. I used a 50¢ US Mobile prepaid sim from Amazon. From what I remember, the sim card must be GSM and not CDMA. Don't worry if you don't use a GSM carrier, that shouldn't matter. I've had this running for about a year now with no hiccups, including occasional losses of power and wifi outages,

1. Purchase inactive sim card (I used this one, but I don't know if the listing is the same because it's been a year).
2. Go to https://airmessage.org/help/guide/phone-number
3. Follow the guide for method 1
4. If that fails, try other methods from that page.

OpenBubbles Only

Validation Relay (No Jailbreak Needed, iOS 14-17.0) [Not recommended]

1. Follow the validation relay guide here.

RelayServer (Requires Jailbreak, iOS 10-14) [Not recommended]

1. Carefully follow the guide here.

Paid Hosting (No hardware required)

1. Sign up for the waitlist (see above).

So what should you use?

Well, that kind of depends. If you don't have access to a Mac and don't want to mess around with getting Docker set up, OpenBubbles is your only option with paid hosting. If you don't want your Mac to be powered on all the time, don't want to disable SIP, or want your phone number registered and have issues with sim swap, OpenBubbles is once again your only option. If you want more features like emoji reactions and facetime, OpenBubbles is once again the only option. If you're not a very technical person, OpenBubbles might feel a lot more comfortable.

So why would you want to go the other route? There are 6 main reasons to pick the BlueBubbles approach:

1. You don't mind your Mac being on 24/7.
2. You don't have a Mac but still want to host it yourself through Docker-OSX or a VM.
3. You care more about keeping iMessage with your other chats in Beeper than you do about the extra features OpenBubbles offers.
4. You care a lot about having your messages on desktop (either through Beeper or the BlueBubbles client).
5. You want to restore existing messages from your Mac/iCloud account.
6. You want to have both set up so you have a fallback if one or the other goes down.

Personally, I use both. I like having my messages in Beeper, both for consolidation and because I want access to my messages on Desktop. If I need features BlueBubbles doesn't have, want to send a large attachment, or my bridge goes down I can just go to OpenBubbles.

Misc other things

• If you're on Ventura, emoji reactions still show up as "Reacted <X> to <message>" with BlueBubbles/the Beeper bridge. You just can't send them, and they don't appear neatly on the message. If your Mac is running Sequoia, they won't show up at all.
• I didn't include VMs in this guide for BlueBubbles because it is more complicated, and also I've just never done it. I didn't want to speak to anything I don't feel confident in my knowledge about here.

Support People

• If you like this gist or my automated setup script, you can find my buymeacoffee at https://buymeacoffee.com/ngencokamin
• If you wanna support the OpenBubbles devs, their donate link is https://www.paypal.com/donate/?hosted_button_id=MUZH6LH6ZGN6G
• To donate to the BlueBubbles devs, go to https://bluebubbles.app/donate/