How to Connect Bluebubbles to OpenClaw

Download BlueBubbles from bluebubbles.app and install it on your Mac. Open the app — it guides you through initial setup with a wizard. The key steps are: 1. Sign in to iCloud in the BlueBubbles setup (it uses your Apple ID to access iMessage) 2. Set a server password — this is your BLUEBUBBLES_PASSWORD credential. Choose something strong but memorable, as you will enter it in OpenClaw's config. 3. Enable the HTTP server. BlueBubbles runs a local HTTP server on port 1234 by default. Note the local IP address shown in the server settings — this becomes your BLUEBUBBLES_URL. 4. Optionally, enable 'ngrok' or 'Cloudflare Tunnel' in BlueBubbles settings if you want to access the server from outside your local network. BlueBubbles has a built-in ngrok integration that generates a public URL automatically. Verify the server is running by opening a browser on the same Mac and navigating to `http://localhost:1234/api/v1/server/info` with your password as a query parameter. You should see a JSON response with server information. Leave BlueBubbles running in the background. On a Mac mini used as a home server, configure it to launch at login: System Settings > General > Login Items > add BlueBubbles.

1# Test your BlueBubbles server is running (run in Terminal on the Mac)
2curl "http://localhost:1234/api/v1/server/info?password=YOUR_PASSWORD"
3
4# Expected response:
5# {"status": 200, "message": "Successfully got server info", "data": {...}}
6
7# Find your Mac's local IP address
8ifconfig | grep 'inet ' | grep -v 127.0.0.1
9# Note the IP (e.g., 192.168.1.50) — this is your BLUEBUBBLES_URL base

Open the OpenClaw config file at `~/.openclaw/config.yaml` and add the BlueBubbles integration configuration. Unlike ClawHub skills, direct API integrations are configured under the `integrations` key rather than `skills`. The `url` field should be the base URL of your BlueBubbles server — either `http://YOUR_MAC_IP:1234` for local network access, or the ngrok/Cloudflare public URL if you need access from outside your network. Do not include a trailing slash. The `password` field is the server password you set during BlueBubbles setup. This is sent as a query parameter on every API request. After saving the config, run `clawhub reload` to apply the changes. OpenClaw will attempt to contact the BlueBubbles server on the next relevant command — you will see a connection confirmation in the OpenClaw log.

1# ~/.openclaw/config.yaml
2integrations:
3  bluebubbles:
4    url: "http://192.168.1.50:1234"   # Your BlueBubbles server URL
5    # OR for ngrok: url: "https://abc123.ngrok.io"
6    password: "YOUR_BLUEBUBBLES_PASSWORD"
7    poll_interval: 30                  # Seconds between inbox checks (default: 60)
8    auto_read: true                    # Mark messages as read after fetching (default: false)
9    send_typing_indicator: false       # Show typing indicator when composing (default: false)

With the config in place, test the connection by using OpenClaw's direct integration commands to send a test message. Because BlueBubbles is a direct API integration (not a ClawHub skill), you trigger it differently from skill-based integrations — you configure OpenClaw to make HTTP calls to the BlueBubbles endpoints directly. The BlueBubbles REST API uses a consistent endpoint pattern. To send a message, POST to `/api/v1/message/text` with the recipient's phone number and message text in the request body. The password is sent as a query parameter on all requests. Test by sending yourself a message first. Use your own iPhone number in international format (e.g., +15550001234). If the message appears on your iPhone, the integration is working correctly. OpenClaw can also call this endpoint through its HTTP integration features or through a configured automation script. The examples below show both the raw curl command for testing and the OpenClaw config approach for automation.

1# Test sending an iMessage via BlueBubbles API (run in terminal)
2curl -X POST "http://192.168.1.50:1234/api/v1/message/text?password=YOUR_PASSWORD" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "chatGuid": "iMessage;-;+15550001234",
6    "message": "Test message from OpenClaw via BlueBubbles",
7    "method": "apple-script"
8  }'
9
10# Test reading recent messages
11curl "http://192.168.1.50:1234/api/v1/chat?password=YOUR_PASSWORD&limit=10"
12
13# Check server status
14curl "http://192.168.1.50:1234/api/v1/server/info?password=YOUR_PASSWORD"

BlueBubbles can notify OpenClaw of incoming messages in two ways: polling (OpenClaw periodically asks the server for new messages) or webhooks (BlueBubbles pushes new messages to OpenClaw). Polling is simpler to set up; webhooks are more real-time but require OpenClaw to be accessible from the BlueBubbles server. For the polling approach, set `poll_interval` in your config (shown in Step 2). OpenClaw will query `/api/v1/message?sort=DESC&limit=10` at that interval and process any messages newer than the last-seen timestamp. For webhook-based delivery, go to BlueBubbles Settings > Notifications > Webhooks and add your OpenClaw webhook URL. BlueBubbles will POST new message payloads to that URL in real time. This requires OpenClaw to have an accessible HTTP endpoint, which is available in OpenClaw Server mode. For most personal and small-team use cases, polling every 30-60 seconds is sufficient and simpler to maintain. RapidDev's team recommends starting with polling and switching to webhooks only if real-time response is a firm requirement for your use case.

1# BlueBubbles webhook payload format (POST to your OpenClaw webhook endpoint)
2# BlueBubbles sends this when a new message arrives:
3{
4  "type": "new-message",
5  "data": {
6    "guid": "message-guid-here",
7    "text": "Message content here",
8    "handle": {
9      "address": "+15550001234"
10    },
11    "dateCreated": 1709123456789,
12    "isFromMe": false,
13    "chat": {
14      "guid": "iMessage;-;+15550001234",
15      "displayName": null
16    }
17  }
18}
19
20# Poll for new messages manually (useful for testing):
21curl "http://192.168.1.50:1234/api/v1/message?password=YOUR_PASSWORD&sort=DESC&limit=5"

With send and receive working, you can build automated response workflows. The pattern is: poll for new messages, filter by sender or keyword, compose a response using OpenClaw's AI, and send the response via the BlueBubbles API. This can be done through OpenClaw's workflow configuration, where you chain the BlueBubbles integration with OpenClaw's language processing capabilities. You configure trigger conditions (new message from a specific number, or message containing a keyword), an AI response generation step, and a send action. For more complex workflows — like routing messages to different response templates based on content, or escalating to a human after a number of AI responses — the OpenClaw workflow engine handles the logic. The config below shows a simple keyword-based auto-reply pattern as a starting point.

1# ~/.openclaw/config.yaml — automated response workflow example
2workflows:
3  imessage-auto-reply:
4    trigger:
5      integration: bluebubbles
6      event: new-message
7      conditions:
8        - field: text
9          contains: ["help", "support", "question"]
10    actions:
11      - type: ai-response
12        prompt: "You received an iMessage asking for help. Reply politely that someone will be in touch within 2 hours."
13      - type: integration-call
14        integration: bluebubbles
15        endpoint: /api/v1/message/text
16        method: POST
17        body:
18          chatGuid: "{{trigger.chat.guid}}"
19          message: "{{ai-response.output}}"
20          method: apple-script