Home Downloads Install FAQ Web App Donate

FAQ

Setup

Q: Can I do this without a Mac?

Yes! You will need to set up a macOS VM on either Windows or Linux. We have a Windows guide pinned on our subreddit, and we can give you additional assistance with Linux and iMessage activation in our Discord.

Disclaimer: This is meant to be done on Apple Hardware

Q: Will I need port-forwarding for this to work?

No, we utilize Ngrok to create a secure tunnel between your server and your client. You can optionally switch to LocalTunnel, which is another tunneling service, or disable this entirely to use your own local IP or dynamic DNS.

Q: Why do I need to sign up for Google's Firebase Service?

BlueBubbles does not require an open socket connection at all times, to reduce battery usage. We use Google FCM to still be able to send notifications even when the app is closed.

Q: Why does the MacOS server require Full Disk Access?

MacOS does not allow app's to read from iMessage's chat database unless they have Full Disk Access.

Features

Q: What is the best macOS device and version to use?

See the following compatibility table for what features are and aren't supported on the various macOS devices and versions:

BlueBubbles Features El Capitan - Catalina Big Sur (Intel) Big Sur (Apple Silicon) Monterey (Intel) Monterey (Apple Silicon)
Sending / Receiving Messages
Sending Attachments
Receiving Attachments
Receiving Tapbacks & Stickers
Receiving Delivered / Read Receipts
Creating DMs
Creating Group Chats

The following table details compatibility for the Private API features. You can find more details about how to use the Private API here.

Private API Features El Capitan - Catalina Big Sur (Intel) Big Sur (Apple Silicon) Monterey (Intel) Monterey (Apple Silicon)
Sending / Receiving Typing Indicators
Sending Tapbacks, Effects, and Subjects
Sending / Receiving Replies
Marking Chats Read on the Server Mac
Renaming & Adding / Removing Participants from Group Chats

Still unsure which version is right for you? Here's a short summary:

  • Stay away from Monterey! No attachment sending is a large drawback.

  • Want Private API features? Don't go for Apple Silicon right now. We hope to support these machines in the near future though!

  • Don't care about creating group chats? Go for Big Sur (Intel), since it supports every other feature. A 2014 or newer Mac Mini is probably best for Big Sur, however Mac Minis as old as 2009 can also be patched to run Big Sur (without graphics acceleration).

  • Need to save some cash? Go for any OS X machine. You'll only miss out on seeing & sending replies. There's usually 2009 Mac Minis on Ebay for $50-$100 that can be patched to run High Sierra, which works just fine for BlueBubbles.

Q: How is BlueBubbles different than AirMessage?

  • Dedicated iOS and Android style themes so you can choose your look

  • Highly community driven, with contributions and suggestions welcomed!

  • Dedicated Desktop apps for Windows and Linux

  • Totally self-hosted, so you don't have to rely on developer servers

  • Tons of customization & settings to personalize your experience

  • Private API features for that extra bit of functionality

Q: Can we react to messages, send effects, send replies, etc?

Yes, we have extra functionality in the form of our Private API bundle. This does require some extra configurations; instructions can be found here.

Q: Does BlueBubbles support SMS?

Not at this time, though we hope to add this feature in the near future!

Security

Q: Is my data encrypted?

Yes, all connections are done over HTTPS/WSS and utilizes TLS encryption by default

Q: Can I share my QR Code?

No, your QR code should be private because it contains your server password and Firebase credentials. If it gets leaked, you should redo your Firebase setup and change your server password to avoid compromising your messages.

Issues

Q: When I send a message, it sends twice and the first one fails. What is the issue?

We aren't 100% sure why this issue happens, however, a simple reboot of the Mac usually fixes the issue. Also, signing up on ngrok's website may help the issue. Do the following:

Register for a free account at ngrok. After registering, you can find your account's Auth Token in their portal. Copy and paste that auth token into the token field within the BlueBubbles macOS Server settings. Copy and paste using CMD + V. Finally restart the server app and/or the Mac itself.

Q: I'm only getting notifications sometimes, what's going on?

Often times, this is due to your phone manufacturer's OS-specific memory management strategies. You can view the full list of phone manufacturers and their respective "Don't Kill My App" Benchmarks, here.

More specifically, the OS employs algorithms to detect which apps are using background memory, and killing them, or just preventing them from starting. As a result, the BlueBubble's background process has a chance of being killed, and you will not receive notifications. On most devices, the manufacturer will provide a way to disable battery optimization (memory management) on certain apps.

This is what you will need to do for BlueBubbles. Find the BlueBubble's App, then tap and hold on it to bring up the menu. Select the (i) Icon, which will take you to the App's Android Settings. Find the list item that pertains to Battery Optimization or Memory Management. You should see a few options to either disable or enable battery optimization. For best results, select the least restrictive setting. In most cases, this will be something like, Do not optimize.

You can find a more in-depth guide on the Don't Kill My App website, by selecting your phone manufacturer.

Note: If you use a Samsung phone, this guide may help you.

Q: Ngrok keeps disconnecting and/or my URL is not updating, what's going on?

There are a couple of different things you can try:

  1. Register for a free account at ngrok. After registering, you can find your account's Auth Token in their portal. Copy and paste that auth token into the token field within the BlueBubbles macOS Server settings. Copy and paste using CMD + V. Finally restart the server app and/or the Mac itself.

  2. Verify you do not have a VPN, Proxy, or Custom DNS blocking Ngrok (this is common on school or work networks)

  3. Try to connect to your server using the manual server URL/password entry

  4. Please make sure your phone time is set automatically rather than manually. We've noticed this can cause connection issues sometimes.

If all else fails, we highly recommend looking into port forwarding as that will have the greatest reliability.

Q: I am not getting any new messages until I open the app, what am I doing wrong?

This may be caused by the time on your Mac device being off from the actual time.

  1. Make sure your Mac devices date and time and timezone is set automatically.

  2. If the time is set automatically then try:

  3. Go to time.is link on your Mac server and it will tell you if your time is not synchronized with the global clock.

  4. If the time is not synchronized then try:

  5. Open up terminal and run "ntpdate -u time.apple.com" (remove the quotes), then restart your Mac.

Q: Every image I send or receive shows up as 'Unknown group event' on my device, am I doing something wrong?

No, you are not doing anything wrong! This is actually a bug with macOS Mojave 10.14 that has not been patched by Apple (this bug may be present on other macOS versions as well). Follow these steps to potentially fix the issue:

WARNING: This process will erase all your Mac's Messages history!

1. Sign out from iMessage from your Mac.
2. Finder -> Go (top bar) -> Library (Hold "Option" key for this to appear)
3. Locate and open "Messages" folder
4. Delete every file that *ends with* .db in the name - if the has an additional extension, you should try this process first WITHOUT deleting those files.
5. Restart your computer
6. Open Messages and sign into iMessage again
7. Delete the BlueBubbles app from your phone.
8. Reboot your phone.
9. Re-install the BlueBubbles macOS Server and sign back into your server.

Q: I'm not getting notifications on my lock screen, but they appear when I unlock my phone. What am I doing wrong?

The issue is with the Android option, "Skip lock screen" after face unlock. This needs to be turned off for the notifications to show.

Other

Q: How can I support the developers?

We don't charge anything for the use of our applications or code, however you can support us by donating on our donations page.

Q: How do I keep my Mac awake, even when I close my laptop lid?

If you are using a Mac Mini or Mac Desktop, where there is no lid, you should be able to use the built-in settings option to "Keep macOS Awake". If you are running macOS on a laptop, you can use an app called Amphetamine to keep your Mac awake.

Q: How can I make sure my Mac starts up after a power failure?

In System Preferences, you must turn on the "Automatically turn back on after a power failure" option in order for your Mac to reboot after a power failure. In addition, turn on the "Startup with macOS" option in the BlueBubbles settings to make sure it runs when you login.