iMessage | Sophon

Sophon connects to iMessage through BlueBubbles, a self-hosted server that bridges Apple's Messages app to an HTTP API. Sophon sends outbound messages to the BlueBubbles REST API and receives inbound messages from a webhook that BlueBubbles calls when a new message arrives.

BlueBubbles requires a Mac. The server runs on a macOS host that is signed in to your Apple ID, and that Mac must stay online for iMessage to work. There is no way to use iMessage without an Apple device acting as the bridge.

Prerequisites

A Mac (always-on) signed in to the Apple ID you want to send and receive as
The BlueBubbles server installed and running on that Mac
A server password configured in BlueBubbles
Network reachability from Sophon to the BlueBubbles server URL, and from BlueBubbles back to Sophon for webhooks

Step-by-Step Setup

1. Install and Configure BlueBubbles

Install the BlueBubbles server on your Mac and grant it Full Disk Access and Accessibility permissions (required to read and send messages)
In the BlueBubbles server settings, set a server password — copy it for later
Note the server URL (for example http://localhost:1234, or a tunnel/LAN address that Sophon can reach)

2. Point BlueBubbles at the Sophon Webhook

Sophon receives inbound iMessages on a webhook endpoint.

In the BlueBubbles server settings, open the Webhooks section
Add a webhook pointing to your Sophon gateway at /webhooks/bluebubbles
Enable the new message event so BlueBubbles forwards incoming messages

Sophon only acts on new-message events and ignores messages you sent yourself (isFromMe), so the assistant will not reply to your own outgoing texts.

3. Configure in Sophon Dashboard

Go to Channels and click Add Channel
Select iMessage (via BlueBubbles)
Enter the BlueBubbles Server URL and Server Password
Click Test Connection — Sophon calls the BlueBubbles server info endpoint to confirm the URL and password are valid
Click Activate

4. Test It

Send an iMessage to the Apple ID running BlueBubbles. Sophon should receive it through the webhook and reply back into the same conversation.

Configuration Reference

These keys come from the adapter's Settings. Both are required.

Field	Type	Required	Description
`serverUrl`	url	Yes	Base URL of your BlueBubbles server (e.g. `http://localhost:1234`). A trailing slash is trimmed automatically.
`password`	secret	Yes	The password configured in your BlueBubbles server settings. Used as the `password` query parameter on API calls.

channels.json Example

The adapter registers its channel type as imessage, which is the value the gateway uses to route messages to the BlueBubbles adapter.

{
  "id": "imessage-bluebubbles",
  "type": "imessage",
  "name": "Sophon iMessage",
  "enabled": true,
  "config": {
    "serverUrl": "http://localhost:1234",
    "password": "<encrypted>"
  },
  "routing": {
    "agentId": "default",
    "dmBehavior": "main-session",
    "groupBehavior": "mention-only"
  }
}

Media Support

The BlueBubbles adapter currently handles text only. Inbound messages are read from the webhook payload's text field, and outbound messages are sent as text via the AppleScript send method. An outbound image is sent as its caption text (or a placeholder), not as a file.

Type	Inbound	Outbound
Text	Yes	Yes
Images	No	No (caption sent as text only)
Audio	No	No
Video	No	No
Documents	No	No

Troubleshooting

Test Connection fails — Verify the server URL is reachable from Sophon and that the password matches your BlueBubbles settings. Sophon validates by calling the BlueBubbles server info endpoint; a wrong password or unreachable host returns an error with the HTTP status.
No inbound messages — Confirm the BlueBubbles webhook points to /webhooks/bluebubbles on your Sophon gateway, the new message event is enabled, and BlueBubbles can reach Sophon over the network.
Sophon ignores some messages — Messages flagged isFromMe are skipped by design, so the assistant never replies to your own outgoing texts.
Replies go to the wrong chat — iMessage routing uses a chat GUID (for example iMessage;-;+1234567890). Sophon derives this from the inbound message; sending to a manually specified recipient requires a valid GUID containing a ;.
Nothing works after the Mac sleeps or signs out — BlueBubbles depends on the Messages app being signed in and the Mac being awake. Keep the host online and prevent it from sleeping.

See also Telegram and Slack for other channel setups.

iMessageNEW