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

本页目录