BlueBubbles (iMessage)

通過自託管在 Mac 上的 BlueBubbles 服務器實現 iMessage 橋接。需要持續運行的 Mac 設備，是所有提供商中部署成本最高的方案。

⚠️ 需要一臺安裝了 BlueBubbles 服務器並登錄 iMessage 賬號的 Mac。 認證方式為單一共享密碼，不支持 HMAC。適合已將 Mac 作為通知橋接節點運營的團隊（安全團隊、運維團隊等）。

功能概覽

出站消息：通過 POST {server}/api/v1/message/text?guid=<password> 發送，請求體包含 {chatGuid, message}。支持通過 selectedMessageGuid 引用回覆。
入站 webhook：掛載在 /webhooks/bluebubbles，監聽 new-message 事件。BlueBubbles 採用"註冊後接收"模式：首次出站時，Minara 會自動在 BlueBubbles 服務器上註冊 webhook URL，此後接收所有新消息事件。
純文本。通過 /api/v1/message/attachment 發送圖片和附件的功能暫未實現。
文本長度上限 16384 字符。

設置步驟

1. 安裝 BlueBubbles 服務器

參照官方 BlueBubbles 服務器安裝指南：

下載 BlueBubbles macOS 應用
在 Mac 上登錄用於橋接的 iMessage Apple ID
配置一個強服務器密碼（即 BLUEBUBBLES_PASSWORD）
將服務器公開訪問。BlueBubbles 支持以下方式：
- Ngrok（內置集成）
- Cloudflare Tunnel
- 靜態 IP 手動端口轉發
從 BlueBubbles 應用的"Status"標籤頁複製公網 URL，填入 BLUEBUBBLES_SERVER_URL。

2. 獲取默認會話 GUID

在 BlueBubbles 桌面端打開目標會話，"Info"面板會顯示會話 GUID，格式如下：

單聊：iMessage;-;+15551234567
群聊：iMessage;+;chat<long hex>@imsgr.icloud.com

將其保存為 BLUEBUBBLES_DEFAULT_CHAT_GUID。

3. 配置 Minara

minara auth messaging add
# 从列表中选择 `bluebubbles`。

或直接設置環境變量：

BLUEBUBBLES_SERVER_URL=https://your-tunnel.ngrok.app
BLUEBUBBLES_PASSWORD=<server password>
BLUEBUBBLES_DEFAULT_CHAT_GUID=iMessage;-;+15551234567

4. 測試

minara auth messaging test bluebubbles

目標會話會收到"✅ Minara gateway test ping"。若 iMessage 已開啟回落 SMS 功能，SMS 部分費用由話費承擔。

入站 webhook

BlueBubbles 是註冊表中唯一使用純共享密碼認證的提供商（無 HMAC，無 JWT）。服務器通過 URL 查詢參數（?guid=<pw>）或 JSON 請求體（password / token 字段）傳遞密碼。Minara 同時兼容兩種格式，並使用恆定時間比較。

webhook 需在 BlueBubbles 服務器後臺手動添加（"Settings" → "Webhooks" → "Add Webhook"）：

URL:    https://<your-host>/webhooks/bluebubbles
Events: new-message

入站 payload 結構：

{
  "type": "new-message",
  "data": {
    "guid": "<message guid>",
    "text": "hello from iMessage",
    "handle": { "address": "+15559876543" },
    "chats": [{ "guid": "iMessage;-;+15559876543" }],
    "dateCreated": 1700000000000,
    "isFromMe": false
  }
}

isFromMe: true 的事件會被過濾，視為自發消息。其他事件類型（updated-message、typing-indicator 等）不作解析。

限制與注意事項

需要持續運行一臺 Mac 並保持 iMessage 登錄狀態。生產可靠性取決於 Mac 的運行時間和 Apple iMessage 服務的狀態。
僅密碼認證。 將 BLUEBUBBLES_PASSWORD 視為長共享密鑰，定期輪換。無 HMAC 意味著密碼洩露即等同於完全身份冒充。
受 Apple iMessage 速率限制約束。 發送過快會觸發運營商或 Apple 側的限速，BlueBubbles 會將其體現為發送失敗。
暫不支持附件。 通過網關發送圖片和文件的功能將在後續版本中補充。

常見問題排查

"BlueBubbles server unreachable"

Mac 側的 tunnel（ngrok / cloudflared）已斷開。重啟 tunnel，若公網 URL 發生變化，同步更新 BLUEBUBBLES_SERVER_URL。

"出站請求返回 401 / 403"

BLUEBUBBLES_PASSWORD 與服務器保存的密碼不匹配。打開 BlueBubbles 桌面應用 → Settings → Server Settings，重置密碼並更新環境變量。

"測試消息未到達目標手機"

iMessage 綁定的是 Apple ID，請確認 Mac 登錄的 Apple ID 正確，且 Messages.app 中該會話處於活躍狀態。
若接收方使用非 Apple 設備，iMessage 會回落至 SMS（取決於運營商支持情況）。

"入站 webhook 未觸發"

BlueBubbles 的 webhook 註冊是服務器級別的，與客戶端無關。打開 BlueBubbles 後臺，確認 webhook URL 指向你的 Minara 主機。

參考資料

環境變量：BLUEBUBBLES_*
出站實現：apps/agent/src/messaging/bluebubbles.ts
入站規範：apps/agent/src/messaging/inbound/specs/bluebubbles.ts
BlueBubbles 官網：bluebubbles.app
REST API 文檔：docs.bluebubbles.app / REST API & Webhooks

本頁目錄