The Mac app

BlueBot sends through a small app in your Mac's menu bar. It takes the texts that are ready, hands each to the Messages app, reads back what Messages did and tells BlueBot. It also copies the conversations you chose back to BlueBot, so your dashboard, your webhooks and your AI assistant see every reply. You set it up once and then leave the Mac alone.

What your Mac needs

• macOS Sonoma (macOS 14) or later.
• Messages signed in with the Apple ID your number uses, the same one on your iPhone.
• To stay on, awake and online. BlueBot can't send while the Mac sleeps. A Mac mini or an iMac is the easiest; a MacBook works if it stays plugged in and open, since closing the lid puts it to sleep.
• Your iPhone, for regular texts. An SMS to someone who isn't on iMessage goes from your iPhone, so Text Message Forwarding must be on for this Mac (on the iPhone, Settings → Apps → Messages → Text Message Forwarding) and the iPhone must be on and connected.
• Full Disk Access for BlueBot, so it can read Messages' database to confirm each text and copy replies. It reads that database and never writes to it.

One account has one Mac and one number. Connecting a second Mac disconnects the first.

Set it up

1. Download BlueBot from Download at the top of usebluebot.com, drag it to Applications and open it. Its icon, two speech bubbles, appears in the menu bar.
2. Press Sign in to BlueBot. Your browser opens BlueBot's dashboard and asks you to confirm Connect this Mac; the browser then hands the Mac a one-time code. The app keeps the token it gets in your Mac's Keychain, and that token is its only credential.
3. The app's window walks you through each check below and fixes what it can for you.
4. Send yourself a test text from the window. The first send is when macOS asks whether BlueBot may control Messages; say OK.

The app adds itself to Login Items, so a Mac that restarts after a power cut or a macOS update goes on sending without anyone opening it. You can take it out in System Settings → General → Login Items, and that choice stays.

The checks

Every 10 seconds the app checks in with BlueBot and reports five checks. Each is ok, needs_you or unknown, and you can read them with GET/v1/device, in the dashboard and in the app's window. When one turns needs_you, BlueBot fires device.check_failed and the menu bar icon shows a dot.

unknown means the app couldn't tell, usually because Messages isn't open yet. checks_ok on the device is true when no check needs you.

curl "https://usebluebot.com/api/v1/device" \
  -H "Authorization: Bearer $BLUEBOT_API_KEY"

{
  "object": "device",
  "status": "online",
  "name": "Dana’s MacBook Air",
  "number": "+15555550100",
  "app_version": "1.0.0",
  "macos_version": "15.1",
  "last_seen_at": "2026-11-13T19:41:00.000Z",
  "checks": {
    "messages": {
      "state": "needs_you",
      "detail": "Messages isn’t signed in to iMessage."
    },
    "full_disk_access": {
      "state": "ok",
      "detail": null
    },
    "forwarding": {
      "state": "ok",
      "detail": null
    },
    "awake": {
      "state": "ok",
      "detail": null
    },
    "filevault": {
      "state": "ok",
      "detail": null
    }
  },
  "checks_ok": false
}

Keeping the Mac awake

A sleeping Mac sends nothing, so this is the check that matters most. Keep it awake, on the Setup page of the app's window, changes the Mac's power settings so it never sleeps and, on a desktop Mac, starts up again by itself after a power cut. macOS asks for your administrator password before anything changes; you type it into macOS, and BlueBot never sees it or keeps it.

The display can still turn off; only the Mac itself has to stay awake. A MacBook is read while it's plugged in, has no setting to start after a power cut, and goes to sleep when its lid closes.

When the Mac is away

The Mac is away when it hasn't checked in for 2 minutes: it's asleep, off, signed out, or off the internet. Then:

• GET/v1/device answers "status": "offline" with offline_since, and device.offline fires.
• Every queued text waits with hold.reason: "device_offline". Nothing fails and nothing is lost, and new sends are still accepted.
• If the Mac stays away 10 minutes, you get one email about it.
• When it checks in again, device.online fires and the waiting texts go in order, at your pace.
• A text still waiting when its expires_at passes (24 hours after it was due, by default) expires and never goes, so a Mac that's away all weekend doesn't send Friday's "Your table is ready" on Monday.

"status": "never_connected" means no Mac has been connected to the account yet.

Pausing

The menu has Pause for an hour and Pause until tomorrow morning (8:00 AM in your account's time zone). While paused, texts are still accepted and wait with hold.reason: "paused", and the menu bar icon dims. Resume from the same menu, the dashboard, or by setting paused_until to null with PATCH/v1/settings, which can also pause until any time you choose.

What it copies

The app copies conversations from Messages to BlueBot, in both directions, so replies reach your webhooks and texts you type yourself on your Mac or iPhone show up too (as source: "mac"). Which conversations is your inbound mode, in Settings or inbound_mode on PATCH/v1/settings:

• replies (the default) copies conversations with people you've texted through BlueBot, and group chats where everyone else is such a person. Your personal conversations stay on your Mac.
• everything copies every conversation with a phone number or an email address, group chats included.

Conversations with short codes and businesses are never copied. When you first connect, the app also copies those conversations from the 7 days before. It copies tapbacks, edits and unsends, and pictures and voice memos up to 25 MB.

Transcribe voice memos, in the menu, turns incoming voice memos into words on the Mac itself with Apple's speech recognition, and the transcript arrives with the memo. It's off until you turn it on.

What it keeps

The app keeps its token in the Keychain and nothing else of yours on disk, apart from the files of texts waiting to send. Those wait in ~/Pictures/BlueBot Outbox/, where Messages can read them, and are deleted once each text is reported, and within an hour otherwise. Nothing the app logs carries the words of a message.

Updates

The app updates itself. It checks for a new version every six hours and installs it only between sends, once every report has reached BlueBot, so an update never leaves BlueBot unsure whether a text went.

What it never does

• It never asks you to turn off System Integrity Protection and never uses Apple's private frameworks. That's why it can't send a tapback, show typing or unsend. Capabilities
• It never writes to Messages' database or changes your conversations.
• It never sends a text twice when it can't tell whether the first one went. That text becomes unconfirmed and waits for you. Message states