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 (Virtual Machine) on either Windows or Linux. We have a handful of guides in our documentation, as well as on our subreddit. We can also assist with any issues such as 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, port-forwarding is not required. We offer built-in proxy services such as Ngrok or Cloudflare to allow the connection to your server. However, those proxy services are hosted by third-parties. If you would like a completely self-hosted setup, we recommend port forwarding with a dynamic DNS.

Some router manufacturers such as Asus sometimes include dynamic DNS plugins and/or Let's Encrypt certificate management to allow you to create a secure connection between a client and your server.

Disclaimer: By using the third-party proxy services, you are accepting their respective licensing and usage agreements.

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

To minimize background battery usage, BlueBubbles does not maintain a direct socket connection between your phone and your server when the app is not in focus. Google's Firebase Service is utilized to send notifications to your device when new messages arrive. It is also used to allow you to perform a server reset when you cannot directly connect to your server.

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 High Sierra - Catalina Big Sur - Monterey Ventura and up
Sending / Receiving Messages
Sending / Receiving Attachments
Receiving Tapbacks, Stickers, and Mentions
Receiving Delivered / Read Receipts
Receiving Replies
Creating DMs
Creating Group Chats ** **
Receiving Edited / Unsent Messages
FindMy Devices

- Replies will show as a regular message on macOS 10.x devices, instead of showing with the replies UI.

** - Group chat creation is possible on macOS 11+, but you must have the Private API configured and enabled.

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 High Sierra - Catalina Big Sur Monterey Ventura and up
Sending / Receiving Typing Indicators
Sending Tapbacks, Effects, Subjects, Mentions, and Rich Links
Sending Replies
Marking Chats Read on the Server Mac
Creating Chats
Renaming, Adding / Removing Participants, & Leaving Group Chats
Updating Group Chat Photo
Editing & Unsending Messages
Marking Chats Unread on the Server Mac
Receiving Digital Touch & Handwritten Messages
Focus Mode
Deleting Messages & Chats
Checking iMessage / FaceTime Availability
FindMy Friends
Incoming FaceTime Notification
Sharing Contact Card
Downloading Purged Attachments
Getting Phone Number Registration Info

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

  • In general, macOS Ventura is the recommended / best version of macOS for BlueBubbles.

  • Need to save some cash? Go for any OS X machine. You'll miss out on the newer iMessage features, but 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 features, 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 can connect to my server when on cellular, but not on WiFi. What am I doing wrong?

The first thing this could be is your device's DNS cache. With Cloudflare, domains are registered on the fly, so your device may not recognize the domain immediately. The solution to that is just to give it time to propogate, and your device time to flush its' DNS cache.

The second thing this could be is any "protection" that your WiFi's service provider might offer as part of their DNS service or router. For instance, some offer McAfee protection, which may block your server URL from being accessed. The solution to this could either be to overwrite your router's DNS server, disable the protection, or whitelist your server URL. To check if this is the case, you can try visiting your server URL on your devices web browser. If you see the landing page, then the app should be able to connect. If you don't see the landing page, you may see the reason why you can't access it.

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 backup my existing BlueBubbles Server data and migrate to a new Mac?

Luckily for you, we have a documentation guide just for this: Migrating Servers

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.