# The Mac app > What the BlueBot app in your menu bar does, what your Mac needs, the five checks it runs and how to fix each, what it means when the Mac is away, and how to keep it awake. 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. | Check (`checks.…`) | What it checks | What the app saw, when it needs you | How to fix it | | ------------------ | ----------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `messages` | Messages is open, signed in to iMessage, and BlueBot may control it. | "Messages isn't signed in to iMessage." or "BlueBot isn't allowed to control Messages." | Press **Open Messages**, sign in with your Apple Account and turn on iMessage in its settings. For the second, turn BlueBot on for Messages in **System Settings → Privacy & Security → Automation**. | | `full_disk_access` | BlueBot can open Messages' database to read sends and replies. | "Messages' database didn't open." | Turn BlueBot on in **System Settings → Privacy & Security → Full Disk Access**. The window's **Open the setting** button takes you there. | | `forwarding` | Messages on the Mac has an account for regular texts, which Text Message Forwarding adds. | "Messages has no account for regular texts." | On your iPhone, turn on **Text Message Forwarding** for this Mac. Without it, iMessages still go, and texts to people without iMessage fail. | | `awake` | The Mac never sleeps, and (on a desktop Mac) starts up again after a power cut. | "This Mac sleeps after 10 minutes." or "This Mac doesn't start up after a power cut." | Press **Keep it awake** in the window's Setup page. See below. | | `filevault` | Whether FileVault is on. | "FileVault is on." | This check only warns you. After a restart, a Mac with FileVault waits at the login screen for your password, and Messages can't open until someone types it. Leave it on and sign in after each restart, or turn it off in **System Settings → Privacy & Security**. | `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. ```bash curl "https://usebluebot.com/api/v1/device" \ -H "Authorization: Bearer $BLUEBOT_API_KEY" ``` ```ts import BlueBot from '@usebluebot/sdk'; const client = new BlueBot({ apiKey: process.env.BLUEBOT_API_KEY }); const device = await client.device.get(); console.log(device); ``` ```python import os from bluebot import BlueBot client = BlueBot(api_key=os.environ["BLUEBOT_API_KEY"]) device = client.device.get() print(device) ``` The answer, `200`: ```json { "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](https://usebluebot.com/docs/concepts/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](https://usebluebot.com/docs/concepts/message-states)