BlueBubbles (macOS REST)

Trạng thái: Plugin tích hợp sẵn, kết nối với BlueBubbles macOS server qua HTTP. Mình khuyên dùng cho tích hợp iMessage vì API phong phú hơn và setup dễ hơn so với imsg channel cũ.

Tổng quan

  • Chạy trên macOS qua BlueBubbles helper app (bluebubbles.app).
  • Khuyên dùng/đã test: macOS Sequoia (15). macOS Tahoe (26) cũng chạy được; tính năng edit hiện đang bị lỗi trên Tahoe, và cập nhật icon nhóm có thể báo thành công nhưng không đồng bộ.
  • OpenClaw giao tiếp với nó qua REST API (GET /api/v1/ping, POST /message/text, POST /chat/:id/*).
  • Tin nhắn đến qua webhooks; tin trả lời, typing indicators, read receipts, và tapbacks là các REST calls.
  • Attachments và stickers được xử lý như inbound media (và hiển thị cho agent khi có thể).
  • Pairing/allowlist hoạt động giống các channels khác (/start/pairing etc) với channels.bluebubbles.allowFrom + pairing codes.
  • Reactions được hiển thị như system events giống Slack/Telegram để agents có thể “mention” chúng trước khi trả lời.
  • Tính năng nâng cao: edit, unsend, reply threading, message effects, group management.

Bắt đầu nhanh

  1. Cài BlueBubbles server trên Mac của các bạn (làm theo hướng dẫn tại bluebubbles.app/install).
  2. Trong BlueBubbles config, bật web API và đặt password.
  3. Chạy openclaw onboard và chọn BlueBubbles, hoặc cấu hình thủ công: 
    {
  channels: {
    bluebubbles: {
      enabled: true,
      serverUrl: "http://192.168.1.100:1234",
      password: "example-password",
      webhookPath: "/bluebubbles-webhook",
    },
  },
}
  4. Trỏ BlueBubbles webhooks về gateway của các bạn (ví dụ: https://your-gateway-host:3000/bluebubbles-webhook?password=<password>).
  5. Khởi động gateway; nó sẽ đăng ký webhook handler và bắt đầu pairing.

Onboarding

BlueBubbles có sẵn trong setup wizard tương tác:

openclaw onboard

Wizard sẽ hỏi:

  • Server URL (bắt buộc): Địa chỉ BlueBubbles server (ví dụ: http://192.168.1.100:1234)
  • Password (bắt buộc): API password từ BlueBubbles Server settings
  • Webhook path (tùy chọn): Mặc định là /bluebubbles-webhook
  • DM policy: pairing, allowlist, open, hoặc disabled
  • Allow list: Số điện thoại, emails, hoặc chat targets

Các bạn cũng có thể thêm BlueBubbles qua CLI:

openclaw channels add bluebubbles --http-url http://192.168.1.100:1234 --password <password>

Kiểm soát truy cập (DMs + groups)

DMs:

  • Mặc định: channels.bluebubbles.dmPolicy = "pairing".
  • Người gửi lạ sẽ nhận pairing code; tin nhắn bị bỏ qua cho đến khi được duyệt (codes hết hạn sau 1 giờ).
  • Duyệt qua:
    • openclaw pairing list bluebubbles
    • openclaw pairing approve bluebubbles <CODE>
  • Pairing là cơ chế token exchange mặc định. Chi tiết: Pairing

Groups:

  • channels.bluebubbles.groupPolicy = open | allowlist | disabled (mặc định: allowlist).
  • channels.bluebubbles.groupAllowFrom kiểm soát ai có thể trigger trong groups khi allowlist được bật.

Mention gating (groups)

BlueBubbles hỗ trợ mention gating cho group chats, giống iMessage/WhatsApp:

  • Dùng agents.list[].groupChat.mentionPatterns (hoặc messages.groupChat.mentionPatterns) để phát hiện mentions.
  • Khi requireMention được bật cho một group, agent chỉ trả lời khi được mention.
  • Control commands từ người gửi được ủy quyền bỏ qua mention gating.

Cấu hình từng group:

{
  channels: {
    bluebubbles: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15555550123"],
      groups: {
        "*": { requireMention: true }, // mặc định cho tất cả groups
        "iMessage;-;chat123": { requireMention: false }, // override cho group cụ thể
      },
    },
  },
}

Command gating

  • Control commands (ví dụ: /config, /model) yêu cầu ủy quyền.
  • Dùng allowFrom và groupAllowFrom để xác định command authorization.
  • Người gửi được ủy quyền có thể chạy control commands ngay cả khi không mention trong groups.

Typing + read receipts

  • Typing indicators: Tự động gửi trước và trong khi tạo response.
  • Read receipts: Điều khiển bởi channels.bluebubbles.sendReadReceipts (mặc định: true).
  • Typing indicators: OpenClaw gửi typing start events; BlueBubbles tự động xóa typing khi gửi hoặc timeout (dừng thủ công qua DELETE không ổn định).
{
  channels: {
    bluebubbles: {
      sendReadReceipts: false, // tắt read receipts
    },
  },
}

Advanced actions

BlueBubbles hỗ trợ các message actions nâng cao khi được bật trong config:

{
  channels: {
    bluebubbles: {
      actions: {
        reactions: true, // tapbacks (mặc định: true)
        edit: true, // sửa tin đã gửi (macOS 13+, lỗi trên macOS 26 Tahoe)
        unsend: true, // thu hồi tin nhắn (macOS 13+)
        reply: true, // reply threading theo message GUID
        sendWithEffect: true, // message effects (slam, loud, etc.)
        renameGroup: true, // đổi tên group chats
        setGroupIcon: true, // đặt icon/ảnh group chat (không ổn định trên macOS 26 Tahoe)
        addParticipant: true, // thêm người vào groups
        removeParticipant: true, // xóa người khỏi groups
        leaveGroup: true, // rời group chats
        sendAttachment: true, // gửi attachments/media
      },
    },
  },
}

Các actions có sẵn:

  • react: Thêm/xóa tapback reactions (messageId, emoji, remove)
  • edit: Sửa tin đã gửi (messageId, text)
  • unsend: Thu hồi tin nhắn (messageId)
  • reply: Trả lời tin nhắn cụ thể (messageId, text, to)
  • sendWithEffect: Gửi với iMessage effect (text, to, effectId)
  • renameGroup: Đổi tên group chat (chatGuid, displayName)
  • setGroupIcon: Đặt icon/ảnh của group chat (chatGuid, media) — không ổn định trên macOS 26 Tahoe (API có thể báo thành công nhưng icon không đồng bộ).
  • addParticipant: Thêm người vào group (chatGuid, address)
  • removeParticipant: Xóa người khỏi group (chatGuid, address)
  • leaveGroup: Rời group chat (chatGuid)
  • sendAttachment: Gửi media/files (to, buffer, filename, asVoice)
    • Voice memos: đặt asVoice: true với audio MP3 hoặc CAF để gửi như iMessage voice message. BlueBubbles chuyển đổi MP3 → CAF khi gửi voice memos.

Message IDs (short vs full)

OpenClaw có thể hiển thị short message IDs (ví dụ: 1, 2) để tiết kiệm tokens.

  • MessageSid / ReplyToId có thể là short IDs.
  • MessageSidFull / ReplyToIdFull chứa provider full IDs.
  • Short IDs lưu trong bộ nhớ; chúng có thể hết hạn khi restart hoặc cache eviction.
  • Actions chấp nhận short hoặc full messageId, nhưng short IDs sẽ báo lỗi nếu không còn khả dụng.

Dùng full IDs cho automations và storage lâu dài:

  • Templates: {{MessageSidFull}}, {{ReplyToIdFull}}
  • Context: MessageSidFull / ReplyToIdFull trong inbound payloads

Xem Configuration cho template variables.

Block streaming

Kiểm soát việc responses được gửi như một tin nhắn đơn hay streamed theo blocks:

{
  channels: {
    bluebubbles: {
      blockStreaming: true, // bật block streaming (hành vi mặc định)
    },
  },
}

Media + giới hạn

  • Inbound attachments được tải về và lưu trong media cache.
  • Giới hạn media qua channels.bluebubbles.mediaMaxMb (mặc định: 8 MB).
  • Outbound text được chia nhỏ theo channels.bluebubbles.textChunkLimit (mặc định: 4000 ký tự).

Tham khảo cấu hình

Cấu hình đầy đủ: Configuration

Các tùy chọn provider:

  • channels.bluebubbles.enabled: Bật/tắt channel.
  • channels.bluebubbles.serverUrl: BlueBubbles REST API base URL.
  • channels.bluebubbles.password: API password.
  • channels.bluebubbles.webhookPath: Webhook endpoint path (mặc định: /bluebubbles-webhook).
  • channels.bluebubbles.dmPolicy: pairing | allowlist | open | disabled (mặc định: pairing).
  • channels.bluebubbles.allowFrom: DM allowlist (handles, emails, E.164 numbers, chat_id:*, chat_guid:*).
  • channels.bluebubbles.groupPolicy: open | allowlist | disabled (mặc định: allowlist).
  • channels.bluebubbles.groupAllowFrom: Group sender allowlist.
  • channels.bluebubbles.groups: Cấu hình từng group (requireMention, etc.).
  • channels.bluebubbles.sendReadReceipts: Gửi read receipts (mặc định: true).
  • channels.bluebubbles.blockStreaming: Bật block streaming (mặc định: true).
  • channels.bluebubbles.textChunkLimit: Kích thước chunk outbound tính bằng ký tự (mặc định: 4000).
  • channels.bluebubbles.chunkMode: length (mặc định) chỉ chia khi vượt quá textChunkLimit; newline chia theo dòng trống (paragraph boundaries) trước khi chia theo độ dài.
  • channels.bluebubbles.mediaMaxMb: Giới hạn inbound media tính bằng MB (mặc định: 8).
  • channels.bluebubbles.historyLimit: Số tin nhắn group tối đa cho context (0 để tắt).
  • channels.bluebubbles.dmHistoryLimit: Giới hạn DM history.
  • channels.bluebubbles.actions: Bật/tắt các actions cụ thể.
  • channels.bluebubbles.accounts: Cấu hình multi-account.

Các tùy chọn global liên quan:

  • agents.list[].groupChat.mentionPatterns (hoặc messages.groupChat.mentionPatterns).
  • messages.responsePrefix.

Addressing / delivery targets

Ưu tiên dùng chat_guid cho routing ổn định:

  • chat_guid:iMessage;-;+15555550123 (ưu tiên cho groups)
  • chat_id:123
  • chat_identifier:...
  • Direct handles: +15555550123, [email protected]
    • Nếu direct handle không có DM chat sẵn, OpenClaw sẽ tạo một cái qua POST /api/v1/chat/new. Điều này yêu cầu BlueBubbles Private API được bật.

Bảo mật

  • Webhook requests được xác thực bằng cách so sánh guid/password query params hoặc headers với channels.bluebubbles.password. Requests từ localhost cũng được chấp nhận.
  • Giữ bí mật API password và webhook endpoint (coi chúng như credentials).
  • Localhost trust có nghĩa là reverse proxy cùng host có thể vô tình bypass password. Nếu các bạn proxy gateway, yêu cầu auth ở proxy và cấu hình gateway.trustedProxies. Xem Gateway security.
  • Bật HTTPS + firewall rules trên BlueBubbles server nếu expose nó ra ngoài LAN.

Troubleshooting

  • Nếu typing/read events ngừng hoạt động, kiểm tra BlueBubbles webhook logs và xác minh gateway path khớp với channels.bluebubbles.webhookPath.
  • Pairing codes hết hạn sau một giờ; dùng openclaw pairing list bluebubbles và openclaw pairing approve bluebubbles <code>.
  • Reactions yêu cầu BlueBubbles private API (POST /api/v1/message/react); đảm bảo server version hỗ trợ nó.
  • Edit/unsend yêu cầu macOS 13+ và BlueBubbles server version tương thích. Trên macOS 26 (Tahoe), edit hiện đang bị lỗi do thay đổi private API.
  • Cập nhật group icon có thể không ổn định trên macOS 26 (Tahoe): API có thể báo thành công nhưng icon mới không đồng bộ.
  • OpenClaw tự động ẩn các actions bị lỗi dựa trên macOS version của BlueBubbles server. Nếu edit vẫn xuất hiện trên macOS 26 (Tahoe), tắt nó thủ công với channels.bluebubbles.actions.edit=false.
  • Để xem status/health info: openclaw status --all hoặc openclaw status --deep.

Để tham khảo workflow chung của channel, xem Channels và hướng dẫn Plugins.