FAQ

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

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.

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.

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

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

† - 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.

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.

• 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

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

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

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

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.

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.

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.

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.

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.

If the time is set automatically then try:

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

If the time is not synchronized then try:

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

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.

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.

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

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

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.

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

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.