# Self-Hosted or Managed iMessage Connections

Canonical: https://figment.so/blog/imessage-self-hosted-vs-managed

There is no official Apple iMessage API. Apple's documented third-party iCloud authorization covers Mail, Calendar, and Contacts — not iMessage. Every iMessage integration, self-hosted or managed, routes through a Mac running the native Messages app. The question is who owns that Mac, and everything attached to it.

**Self-hosted** means you buy or rent the hardware, keep macOS current, configure the network, install and maintain the bridge software, and personally handle reconnection every time Apple's session expires or the hardware fails.

**Managed** means a provider handles that entire infrastructure layer. You wire up an API after a user-consent flow and own the application logic — nothing below it.

## What running your own bridge actually demands

The two most widely used open-source bridges are BlueBubbles and AirMessage.

BlueBubbles requires macOS Sierra or newer with iMessage already activated on the host device. The server is primarily written in TypeScript and continuously polls `chat.db` for new messages. Deeper iMessage integration depends on an optional Private API Bundle built in Objective-C. The Mac can run on physical hardware or inside a Docker-hosted macOS VM, though VM setups carry their own complexity.

AirMessage requires macOS 10.13 or newer. The Mac must stay powered and online around the clock with sleep disabled. Remote access requires port 1359 to be forwarded on your router, or a relay substituted for it. macOS Mojave and later add an explicit Automation permission before AirMessage can read Messages.

Both bridges share the same underlying constraint: the Mac is a single point of failure. When it restarts, loses connectivity, or Apple refreshes the iMessage session, your integration goes offline until someone fixes it. Add to that: keeping bridge versions current, rotating credentials when an Apple Account changes, and monitoring uptime across the bridge, the forwarded port, and any relay service.

## How a managed connection works

In a managed model the provider runs the Mac infrastructure. What you configure is the application-level integration.

Figment's approach: a user approves access through Figment's hosted consent screen, producing a scoped grant for your application. Your app receives a Figment access token — the developer application never sees the user's Apple password. iMessage history and search both use `messages:read`; sending requires a separate `messages:send` scope and is limited to conversations the user explicitly authorizes.

Pricing is $29 per month per active live connection. Sandbox access is free and uses synthetic data that cannot reach real recipients. Access starts after setup; provisioning is not immediate.

Connections move through a defined lifecycle — `connecting`, `needs_approval`, `syncing`, `ready`, `offline`, `reconnect_required`, `revoked`. Read and send operations are rejected on any non-`ready` connection; a `syncing` status is not a partial-success state. Even after reaching `ready`, native history may still be incomplete — check `historyComplete` and `hasMore` in responses rather than assuming full coverage.

For the full OAuth flow mechanics, see [OAuth for iCloud: Connect Apple Data to Your App](/oauth-for-icloud).

## Responsibility matrix

The table below shows who owns each infrastructure and product layer.

| Responsibility | Self-Hosted | Managed (Figment) |
|---|---|---|
| Mac hardware procurement | Developer | Provider |
| macOS version & security updates | Developer | Provider |
| iMessage account activation | Developer | Account owner (via setup flow) |
| Network relay / port forwarding | Developer | Provider |
| Bridge software installation & updates | Developer | Provider |
| Infrastructure reconnection monitoring | Developer | Provider |
| Apple account re-authentication† | Developer | Account owner |
| API authentication & token lifecycle | Developer | Provider |
| Per-user consent & scoped grants | Developer (custom build) | Built-in |
| Idempotency & delivery receipts | Developer (custom build) | Built-in |
| Uptime monitoring | Developer | Provider |
| Application logic | Developer | Developer |

† When a connection enters `reconnect_required` or `needs_approval`, the account owner must complete Apple sign-in or trusted-device approval again. The provider monitors connection state and surfaces these statuses; it cannot perform Apple authentication on behalf of the account owner.

Application logic is the only row that never moves. Everything above it either transfers to the provider or shifts to the account owner in the managed model.

## When self-hosting is the right call

Self-hosting makes sense in a specific set of scenarios:

- **You already operate a Mac fleet.** If a dedicated Mac is already on the shelf, the marginal cost of running a bridge is low.
- **Data must stay on-premises.** Some regulated environments restrict cloud-hosted message proxies. A bridge on internal hardware may satisfy that constraint in ways a managed provider cannot.
- **Single-user personal tooling.** A personal automation that reads your own iMessages rarely justifies a monthly connection fee or a production-grade consent flow.
- **Budget is the binding constraint.** Open-source bridge software is free. If occasional reconnection interruptions are acceptable, the cost is time rather than money.

## When managed wins

The managed model tends to win whenever a product grows beyond a single developer or a single account.

- **Multi-user products.** Per-user consent and scoped grants — essential for any iMessage CRM, AI agent, or team inbox tool — are built into the managed flow. Self-hosting requires you to design and build that layer yourself.
- **No Mac ops capacity.** A team without macOS infrastructure experience that needs iMessage access should not spend engineering weeks building and maintaining one.
- **Idempotency and receipts out of the box.** A send accepted at the bridge is not proof of delivery. Managed providers supply receipt tracking and idempotency enforcement so your application does not need to implement them independently.
- **Lower setup burden.** Managed setup requires no Mac procurement, network configuration, or bridge software installation. You can reach the free sandbox within a developer registration and consent flow; access to a live connection starts after setup is complete.

For detailed feature comparisons, see [Figment vs BlueBubbles for iMessage Integration](/blog/figment-vs-bluebubbles) and [Figment vs AirMessage for App Integrations](/blog/figment-vs-airmessage).

## Migration checklist: moving from a self-hosted bridge

If you run a bridge today and are evaluating a move to managed, work through these steps before you cut over. This is a planning checklist grounded in the supplied API specification; complete sandbox validation before switching any production traffic.

1. **Inventory your current bridge.** Record the bridge software name and version, macOS version, relay or port-forwarding configuration, and every webhook URL your existing integrations call.
2. **Register on the Figment developer dashboard** at [/apple-connect/developers](/apple-connect/developers) and note your `client_id`.
3. **Run sandbox tests first.** Sandbox is free and uses synthetic data. Exercise `GET /v1/connections/{connection_id}/chats` and `POST /v1/connections/{connection_id}/messages/send` before touching any live connection.
4. **Check the chatGuid format.** ChatGuids returned by the Figment API are specific to the connected Mac and are not portable from your existing bridge. Update any hard-coded values in your application.
5. **Audit your idempotency key strategy.** Generate one key per intended action before the first request; reuse it only for that exact action and body. A body-hash strategy can silently merge two separately intended identical messages.
6. **Confirm scope coverage.** Ensure `messages:send` is included in the user grant for every conversation you need to write to. A conversation visible in read results is not automatically authorized for sends.
7. **Run old bridge and new connection in parallel** for a brief test period. Compare read results and note any history gaps caused by sync lag on the new connection.
8. **Cut over reads first.** Redirect history and search calls to the Figment endpoints. Check `historyComplete` and `hasMore` before assuming complete coverage.
9. **Cut over sends.** Migrate send calls last. Verify receipt status — `submitted`, `delivered`, `read`, `failed`, or `unknown` — before you retire the old bridge send path. Do not resend an `unknown` action under a new idempotency key.
10. **Decommission the bridge.** Remove port-forwarding rules, revoke bridge automation permissions in macOS System Settings, and free the hardware.

---

Ready to try without committing to a live connection? [Connect Apple Account](/apple-connect/developers) and start in the free sandbox today.

Also see [Figment vs Claw Messenger for iMessage Apps](/blog/figment-vs-claw-messenger) for another managed-service comparison.