# iMessage (Beta) Bring iMessage into your unified inbox. Connect a Mac running [BlueBubbles](https://bluebubbles.app) and your iMessages flow into the platform alongside WhatsApp, SMS, Instagram, and Messenger — with the same AI Agent, Broadcasts, and contact history you already use everywhere else. > **Beta channel.** iMessage support is currently invite-only while we polish the experience. Reach out to support to enable it on your account. Functionality, limits, and behaviour may change as the channel matures. --- ## Overview Apple doesn't offer an official iMessage API — a set of rules that would let other apps connect to iMessage directly. Instead, this integration connects through an open-source bridge app called **BlueBubbles**, which you run on a Mac that's signed in to your iMessage account. Once connected, the platform: - Receives incoming iMessages as new conversations in Chats. - Sends outbound replies through your Mac, so they appear to recipients as a normal blue-bubble iMessage from your Apple ID. - Lets your AI Agent, tags, and contact records work exactly as they do on every other channel. Setup takes around 10 minutes once you have BlueBubbles installed. --- ## What You Need To connect iMessage, you'll need all of the following: - **A Mac** (laptop or desktop) signed in to your Apple ID with iMessage enabled in the Messages app. - **The Mac must stay online and awake.** If your Mac sleeps, restarts, or loses internet, iMessages stop flowing until it's back online. - **BlueBubbles Server** installed on that Mac — a free, open-source app available at [bluebubbles.app](https://bluebubbles.app). - **A way to expose your Mac to the internet** — typically a tunnel like Cloudflare Tunnel, ngrok, or Tailscale. BlueBubbles' setup wizard will guide you through this. - **A paid plan** — iMessage is included as part of your channel allowance on all current plans. --- ## Setting Up BlueBubbles BlueBubbles is a separate, third-party application that you install on your own Mac. We don't host it — it runs locally on your machine. 1. Download and install **BlueBubbles Server** from [bluebubbles.app](https://bluebubbles.app). 2. Grant the permissions the installer asks for (Accessibility, Full Disk Access, Automation). These let BlueBubbles read incoming messages and trigger the Messages app to send outgoing ones. 3. Open BlueBubbles → **Settings → API & Webhooks**. 4. Set a **server password**. 5. Copy your **server URL** (a public address that points to your Mac). 6. Verify in BlueBubbles that incoming and outgoing test messages work locally before moving on. > Full setup instructions, troubleshooting, and platform-specific guides live in the [official BlueBubbles documentation](https://docs.bluebubbles.app). If you get stuck on BlueBubbles itself, their docs and community are the fastest path. --- ## Connecting BlueBubbles to the Platform Once BlueBubbles is running on your Mac: 1. In the left sidebar, click **Settings** near the bottom. 2. In the Settings left rail, under **Channels**, click **Channels**. 3. Find the **iMessage** card and click **Connect**. (The **Connect** button only becomes clickable once iMessage has been enabled for your account — until then it's grayed out and the card shows the note "iMessage is in private beta and isn't enabled on your account yet.") 4. Paste your BlueBubbles **Server URL** (e.g. `https://your-tunnel.example.com`). 5. Paste your BlueBubbles **server password**. 6. Click **Connect**. We verify the connection by reaching out to your BlueBubbles server and wire the webhook automatically (a webhook is a web address that lets BlueBubbles automatically tell the platform the moment a new message arrives). If everything checks out, the status flips to **Connected**. 7. In BlueBubbles, open **Settings → API & Webhooks → Webhooks** and confirm (or paste) the webhook URL shown on the iMessage settings page. 8. Save. That's it — incoming iMessages now arrive in your inbox in real time. ### Testing the Connection From the iMessage settings page, you can send a test iMessage to any phone number to confirm everything is wired correctly. Enter the recipient's phone number in E.164 format (e.g. `+14155551234`) along with a short message and send the test. The first test send can take up to a minute, because the Messages app on your Mac may need to start a new conversation thread. Subsequent sends are near-instant. --- ## How Messages Flow ### Incoming 1. Someone sends an iMessage to your Apple ID. 2. The Messages app on your Mac receives it (just like normal). 3. BlueBubbles detects the new message and POSTs it to the webhook URL. 4. The platform creates a contact (if new), drops the message into Chats, and — if your AI Agent for this channel is active — it replies. ### Outgoing 1. You or the AI send a reply from the platform. 2. We send the message to your BlueBubbles server. 3. BlueBubbles tells the Messages app on your Mac to send the iMessage. 4. The recipient sees a normal blue-bubble iMessage from your Apple ID. ### Supported Message Types - **Text messages** — fully supported in both directions. - **Attachments and media** — incoming attachments are visible in BlueBubbles but are **not yet** ingested into the platform during the Beta. Outgoing messages must contain text — sending images or files through iMessage isn't available yet. --- ## Sending Limits, Warm-up & Follow-up Controls iMessage has the same kind of protective send limits, automatic warm-up, and follow-up kill switch that WhatsApp Web and Telegram have, with one difference worth knowing: **on iMessage, automated follow-ups are turned on by default** on a newly connected account, so switch them off yourself if you want the account to stay quiet while it warms up. Apple aggressively flags accounts that behave like bulk senders, so these guardrails exist to keep your Apple ID safe. You'll find a **Send Limits & Warm-up** card and an **Automated Follow-ups** toggle on the iMessage settings page once you're connected. ### Automatic warm-up (ramp) A newly connected iMessage account is intentionally throttled and unlocks more capacity over time. It earns a "qualifying day" only on days it actually sends at least 75% of its current cap — idle days don't count. - **Daily message cap** = `50 + 8 × (day − 1)`, capped at **500/day** (reached at day 58). - **Daily new-contact cap** = `floor((day − 1) × 5 / 6)`, capped at **50/day** (reached at day 61). The settings page shows the current ramp day, today's usage against the cap, and how far it has to go. If your Apple ID already has long genuine iMessage history, you can move the ramp-day slider forward — but only do that honestly, for an account that really has that history. ### Beyond-ramp manual override After the full 58-day ramp, an optional override lets you push the daily message cap above 500 (750 up to 5,000, in 250-message steps). Keep it conservative — Apple doesn't publish a safe number, and over-sending risks your Apple ID. The override is only available once the account is fully ramped. ### Send limits on/off & follow-up kill switch A master toggle enables or disables the send limits, and a daily new-contact ceiling lets you cap first-touches lower than the ramp would allow. The **Automated Follow-ups** toggle stops all automated follow-ups for the account regardless of Broadcast/campaign settings. **On iMessage this toggle starts switched on**, so a freshly connected account will send automated follow-ups until you turn it off — and turning it off is recommended while the account is fresh (under ~30 ramp days). When the daily cap is hit, scheduled follow-ups are pushed to the next day instead of failing. --- ## Limitations of the iMessage Beta Because iMessage doesn't have an official API, this channel comes with constraints you won't see on WhatsApp, SMS, or Instagram. Please review these carefully before relying on iMessage for business-critical messaging. - **Your Mac must stay online and awake.** No Mac, no iMessages. We recommend disabling sleep on the Mac running BlueBubbles, or using a dedicated Mac mini for this. - **One-to-one, phone-number conversations only.** Group chats and Apple-ID (email) handles are not officially supported during Beta and may behave unexpectedly if they reach the platform — only use phone-number, one-to-one iMessage conversations. - **Text only.** Attachment-only messages (photo, video, file) are skipped on incoming, and outbound sends must contain message text. Sending media will be added later in Beta. - **No template or pre-approved messages.** All messages are free-form text. - **No delivery or read receipts** in the platform UI. You'll still see them in the Messages app on your Mac. - **A "Sent" status means handed off, not delivered.** A "Sent" status means the platform handed the message to your Mac, not that the recipient received it. Because iMessage has no reliable delivery confirmation, some sends are marked "Sent" optimistically even when your Mac couldn't confirm delivery (for example, if the recipient isn't on iMessage). To be sure a message went through, check the Messages app on your Mac. - **Typing indicators require the BlueBubbles Private API.** When the AI is composing a reply, your contact sees a "typing…" bubble — but only if you've enabled the **Private API** features in BlueBubbles (Settings → Private API). Without it, replies still send normally; the contact just won't see the typing bubble first. - **First outbound message to a new contact can be slow.** Starting a brand-new conversation can take up to 30–60 seconds while macOS opens the thread; subsequent messages are fast. - **No bulk / broadcast blast sending.** During Beta, iMessage is best used for inbound conversations and one-to-one replies, not high-volume outbound broadcasts. Apple aggressively rate-limits and flags automated iMessage traffic. - **Account risk.** Apple does not officially sanction third-party iMessage automation. Excessive or spammy use of iMessage automation can result in your Apple ID being flagged or restricted by Apple. Use the channel responsibly. --- ## Troubleshooting ### "Could not reach the BlueBubbles server" - Confirm BlueBubbles is running on your Mac and the green **Server running** indicator is showing. - Confirm your tunnel (Cloudflare / ngrok / Tailscale) is up and the URL you pasted is reachable from the public internet — open it in a browser, you should see a BlueBubbles welcome page. - Double-check the server password matches the one set in **BlueBubbles → Settings → API**. ### Incoming Messages Not Appearing in the Inbox - Open **BlueBubbles → Settings → API & Webhooks → Webhooks** and confirm the webhook URL we showed you is saved exactly as displayed. - From the iMessage settings page, use **Refresh status** to verify the connection is still healthy. - Make sure the sender's number is a phone number, not an email address (email handles are not supported in Beta). - Confirm your Mac has internet connectivity and is awake. ### Outbound Messages Failing to Send - Test the same recipient directly from the Messages app on your Mac. If Messages.app can't send it either (e.g. recipient isn't on iMessage), the platform can't either. - Make sure your Mac isn't asleep, locked with FileVault, or showing a system update dialog — these block AppleScript automation, which BlueBubbles relies on. - Confirm you have sufficient credits on your account. ### Status Shows "Connected" but Nothing Works - Use **Refresh status** on the iMessage settings page to re-verify the connection. - If it still fails, disconnect, then reconnect with a fresh server URL and password. ### My Mac Restarted / Lost Internet When your Mac comes back online and BlueBubbles starts back up, the connection resumes automatically. Any messages sent to you while the Mac was offline will appear in the Messages app once it reconnects, but they may **not** all be replayed into the platform — iMessage doesn't expose a reliable backfill API. --- ## Need Help? iMessage is currently in **Beta**. If you run into issues we haven't covered above, reach out to hi@youraiconnector.com with: - The server URL you connected (without the password). - A description of the issue and any error messages from the iMessage settings page. - The time the issue happened. We'll take a look as soon as we can.