BlueBubbles (iMessage)
BlueBubbles is an open-source iMessage server that runs on a Mac. Matilda uses it to receive messages via webhook and to reply the way a person does in a thread: texts, tapbacks, threaded replies, the typing bubble, read receipts, and the occasional full-screen effect.
For a guided setup see the Connect iMessage tutorial.
Requirements
- A Mac signed in to iMessage with BlueBubbles Server installed
- The Private API enabled in BlueBubbles, with its helper connected. Tapbacks, threaded replies, effects, the typing bubble and read receipts all need it, and on macOS 26 it is also the only send path that works for a thread with no prior history. The Setup page's Test button says whether it is connected.
- Network reachability in both directions: Matilda to the BlueBubbles API, and BlueBubbles to Matilda's webhook
Settings
| Setting | Env var |
|---|---|
| URL | BLUEBUBBLES_URL |
| Password | BLUEBUBBLES_PASSWORD |
| Webhook token | MATILDA_WEBHOOK_TOKEN, normally generated on Setup instead |
| Screen effects on milestones | MATILDA_IMESSAGE_EFFECTS (default on), also a checkbox on Setup |
| Reply pacing | MATILDA_REPLY_SETTLE_SECONDS (2.5), MATILDA_REPLY_MAX_HOLD_SECONDS (20) |
| Photos | MATILDA_LLM_VISION: auto (Kimi yes, Cerebras no), on, off |
Webhook
Matilda receives events at POST /webhook. The Setup page generates a token and displays the full URL to register in BlueBubbles under API & Webhooks, Manage Webhooks, Add Webhook. Subscribe it to:
| Event | What Matilda does with it |
|---|---|
| New Messages | Texts and attachments start a reply. Tapbacks on her messages, and the agent's own replies typed on the Mac, are kept as context. Her own sends echoing back are dropped. |
| Message Updates | Edits and unsends of a lead's message (answered again only when it matters), and delivery and read receipts on hers. |
| Typing Indicators | She waits while the lead is still typing before answering. |
| Message Errors | A failed send is flagged on the transcript. |
With no token generated and none in the environment, the webhook accepts unauthenticated posts. Generate a token before exposing Matilda publicly. Generating again rotates it, so update BlueBubbles afterward.
Duplicate deliveries are dropped. Matilda remembers the last 1,000 event keys for 120 seconds.
Test
The Setup Test button calls the BlueBubbles ping endpoint to confirm the URL and password, then reports the server version and whether the Private API helper is connected.
Networking
On the same LAN, use the Mac's LAN address. For a cloud-hosted Matilda the reference deployment runs a WireGuard tunnel with the server at 10.100.0.1 and the Mac at 10.100.0.2. Set MATILDA_NETWORK_MODE=host on a Linux server so the container uses the host's WireGuard route. See Deployment.
Behavior
- One-to-one only. Messages from group threads are ignored; Matilda never replies into a group.
- Pacing. A lead who sends "hey", "quick question", then the question gets one reply once they pause. If BlueBubbles reports they are still typing, she holds (up to the configured cap). One turn runs at a time per contact.
- Read and typing. Before composing she marks the thread read and shows the typing bubble, kept alive until the reply lands.
- Replies. At most one reply per turn, optionally as two bubbles a beat apart when it naturally has two parts. When several messages arrived she may thread the reply under the one she is answering.
- Tapbacks. A pure acknowledgement may get only a tapback; anything that needs an answer gets text. She can pick which of several messages to react to.
- Effects. Confetti, balloons, fireworks or a celebration on a real milestone only (pre-approval, a booked showing), and only when the Setup checkbox is on.
- Photos and files. She is told what arrived (photo, PDF, voice memo) and, when the active model supports vision, what a photo shows. She responds to the content, not to the fact that a file arrived.
- Thread context. Tapbacks on her messages, edits, unsends and replies the agent typed on the Mac reach her as context on the next turn. A like needs nothing back; a "?" tapback or an edit that changes the meaning gets a short reply.
- Threads. Replies go back on the thread the lead's texts arrive on. An SMS (green bubble) thread gets plain texts only.
- Over the web chat, where none of this applies, she replies with text only.