Skip to main content

Connect iMessage

Matilda talks over iMessage through BlueBubbles, an open-source iMessage server that runs on a Mac. This tutorial links a BlueBubbles server to a running Matilda instance.

Prerequisites​

  • Matilda running, with a Kimi key configured. See Quickstart.
  • A Mac signed in to iMessage with BlueBubbles Server installed.
  • The Mac and Matilda able to reach each other over the network. On the same LAN this is automatic. For a cloud-hosted Matilda, see Networking below.

1. Enable the Private API in BlueBubbles​

In BlueBubbles Server, open Settings, then API & Webhooks, and enable the Private API. This is what lets Matilda add tapback reactions. Note the server password.

2. Tell Matilda where BlueBubbles is​

You can do this in .env or live on the dashboard. The dashboard value wins and needs no restart.

On the dashboard: open Setup, expand the BlueBubbles panel in the Integrations sidebar, and enter the URL and password. Click Test. Matilda pings the BlueBubbles API and confirms.

In .env:

BLUEBUBBLES_URL=http://192.168.1.20:1234
BLUEBUBBLES_PASSWORD=your-bluebubbles-password

The URL is the Mac's LAN IP and the BlueBubbles port.

3. Generate the webhook URL​

Still on Setup, in the BlueBubbles panel, click Generate next to the incoming webhook URL. Matilda creates a secret token and shows a complete URL of the form:

https://your-matilda-host/webhook?token=...

Copy it. Only Owners can generate or rotate this token.

warning

If no token has ever been generated and none is set in .env, the /webhook route accepts unauthenticated posts. Always generate one before exposing Matilda to the internet.

4. Register the webhook in BlueBubbles​

In BlueBubbles Server, open API & Webhooks, then Manage Webhooks, and click Add Webhook. Paste the URL, subscribe to New Messages, and save.

5. Send a test text​

From another phone, text the number the Mac is signed in with. Within a few seconds Matilda replies in the same thread. Open Leads on the dashboard and you will see the new contact.

Duplicate deliveries are handled. Matilda de-duplicates on the message identifier within a two-minute window.

Networking​

Same LAN. Use the Mac's LAN IP for BLUEBUBBLES_URL. BlueBubbles must be able to reach Matilda's webhook, so Matilda's port must be open to the Mac.

Cloud-hosted Matilda. The reference deployment uses a WireGuard tunnel between the server and the Mac. The server is 10.100.0.1 and the Mac is 10.100.0.2, so BLUEBUBBLES_URL=http://10.100.0.2:1234. Configuration templates live in the infra/wireguard/ folder of the webapp repository. See Deployment.

Next steps​