# Figment vs BlueBubbles for iMessage Integration

Canonical: https://figment.so/blog/figment-vs-bluebubbles

Both Figment and BlueBubbles reach iMessage through a Mac running the Messages app — a constraint Apple imposes because iMessage remains a native platform service with no public programmatic API. The structural difference is who owns and operates that Mac. BlueBubbles is open-source software you install on a Mac you manage. Figment is a hosted service that manages the Mac for you and adds a scoped, per-app grant layer on top. Neither is Apple-authorised iMessage infrastructure: Apple's documented third-party account authorisation covers Mail, Calendar, and Contacts, not iMessage.

## How each tool reaches iMessage

BlueBubbles is a TypeScript server you install on a Mac with iMessage activated. It uses AppleScript to send messages and create chats, and polls the Messages `chat.db` database to detect incoming messages. An optional Private API bundle — written in Objective-C — adds deeper iMessage functionality beyond what AppleScript can reach; the [BlueBubbles Private API documentation](https://docs.bluebubbles.app/private-api/installation) states that enabling it requires disabling System Integrity Protection (SIP). Basic messaging does not require the Private API. For currently supported macOS versions, see the [BlueBubbles server documentation](https://docs.bluebubbles.app/server). BlueBubbles is [licensed Apache 2.0](https://github.com/BlueBubblesApp/bluebubbles-server/blob/master/LICENSE) with an explicit disclaimer that it is not affiliated with or endorsed by Apple.

Figment routes operations through a hosted, isolated Mac that Figment operates. A signed-in Mac executes native Apple operations; a hosted API manages per-app grants, jobs, receipts, and connector coordination. The developer's app connects through a scoped grant — not through the Apple Account password. Each service tracks its own connection state independently; a signed-in account is not the same as a service that is ready to accept operations.

## Figment vs BlueBubbles: key differences

| Dimension | BlueBubbles | Figment |
|---|---|---|
| **Hosting** | Self-hosted Mac you provision, network, and maintain | Hosted isolated Mac operated by Figment |
| **Account ownership** | Your Apple Account logged directly into the Mac you control; clients authenticate using a server password | Account owner approves a scoped grant via Figment's connection screen; your app receives a bearer token, never the Apple password |
| **API** | REST API served from your Mac, authenticated via server password | Hosted REST API; bearer token; per-app scoped grants (`messages:read`, `messages:send`); idempotency key required on every send |
| **Responsibilities** | Self-hosted operator owns Mac uptime, network connectivity, and recovery | Figment manages hosted infrastructure; account owner completes Apple sign-in, approval, permissions, and reconnection when needed |

## Hosting and Mac operations

With BlueBubbles, you are the ops team. The Mac must stay online, iMessage must remain activated, and the server must be reachable by its clients; internet exposure or a tunnel is needed only for remote access. BlueBubbles ships three built-in proxy options — Cloudflare, zrok, and ngrok — each with their own bandwidth and file-size ceilings. Manual dynamic DNS with port forwarding and SSL via CertBot is also documented. Consult the [current BlueBubbles server documentation](https://docs.bluebubbles.app/server) for up-to-date proxy limits and supported macOS versions.

With Figment, hardware, networking, and the OS environment are operated by Figment. The account owner still completes Apple sign-in, trusted-device approval, and Mac permission grants during setup, and may need to complete a reconnection step when Apple requires reauthorisation.

## API design and the permissions model

Figment's iMessage API is served from `https://figment.so/api/apple-connect`. Access requires a Figment OAuth access token obtained through a PKCE flow — not the Apple Account password. Register your app at [/apple-connect/developers](https://figment.so/apple-connect/developers) to receive a `client_id`.

There are exactly two iMessage scopes. `messages:read` covers reading chat history and searching messages. `messages:send` covers outbound sends. Issuing one does not imply the other. A chat appearing in read results is not automatically authorised for sends — the send grant must include that specific existing conversation. Every send requires a stable idempotency key generated and persisted before the first attempt; reuse the same key only for that exact action and body. If a receipt shows `unknown`, poll the same receipt endpoint; do not resend under a new key.

The connection state endpoint requires a valid bearer token and a ready, non-revoked service. It can reject non-ready or revoked connections rather than returning a diagnostic state object. For setup status and connection management, use [/apple-connect/account](https://figment.so/apple-connect/account). When building audit logging for your integration, omit passwords, verification codes, and message bodies from the records your application stores.

BlueBubbles exposes its API directly from your Mac via a server password. Whether to layer per-app grant controls or idempotency handling on top is a design decision your integration will need to address.

## Delivery, sync, and SMS/MMS/RCS

iMessage history available through both tools is limited to what is synced to the Mac at the moment of the query. With Figment, the service must be `ready` before read operations succeed. BlueBubbles reads directly from `chat.db`; messages not yet synced to that Mac are not present, though locally-synced history may remain accessible even when an iPhone is offline.

For carrier traffic (SMS, MMS, RCS), Apple supports two paths to get those messages onto a Mac: Messages in iCloud — which includes SMS, MMS, and RCS forwarding and keeps history current across devices — and separate Text Message Forwarding for real-time relay without full iCloud sync. Either way, the iPhone must be on, online, signed into the same Apple Account, and able to send and receive. See [Apple support article 102545](https://support.apple.com/en-us/102545) for current setup paths. This is a constraint of Apple's Messages continuity, not a limitation of either bridge.

## Access and pricing

Figment developer access starts after setup. The developer pays $29 USD per month per active live connection. Sandbox access is free and includes synthetic data — it cannot send to real people.

BlueBubbles is free, open-source software (Apache 2.0). You provide and maintain your own hardware and hosting; that cost depends on your infrastructure choices. The project does not currently charge an API fee.

## Which to choose

**BlueBubbles** fits a solo developer or small team with an existing Mac and comfort managing server infrastructure. Application-layer grant controls and idempotency handling are decisions you make and implement yourself. It is an established open-source project with an active community, full code visibility. If those properties match your situation, it is a solid foundation.

**Figment** fits a production app or autonomous agent that serves multiple users, needs to issue different apps different scoped permissions, and benefits from managed infrastructure rather than operating a Mac server directly. The grant model and observable connection states exist specifically for integration use cases where failures need to be named and surfaced to users rather than diagnosed through server logs.

To connect iMessage to your app without managing Mac infrastructure, [Connect Apple Account](https://figment.so/apple-connect/developers) to get started.