Skip to main content

BlueBubbles（iMessage）

通过 BlueBubbles 将 Hermes 与 Apple iMessage 连接 —— 一款免费、开源的 macOS 服务器，可将 iMessage 桥接到任意设备。

前提条件​

  • 一台 Mac（持续开机）并运行 BlueBubbles Server
  • 在该 Mac 上的 Messages.app 中已登录 Apple ID
  • BlueBubbles Server v1.0.0 或更高版本（Webhook 功能需要此版本）
  • Hermes 与 BlueBubbles 服务器之间的网络连通性

设置步骤​

1. 安装 BlueBubbles Server​

从 bluebubbles.app 下载并安装。完成设置向导 —— 使用您的 Apple ID 登录，并配置连接方式（本地网络、Ngrok、Cloudflare 或动态 DNS）。

2. 获取服务器 URL 和密码​

在 BlueBubbles Server → 设置 → API 中记录以下信息：

  • 服务器 URL（例如：http://192.168.1.10:1234）
  • 服务器密码

3. 配置 Hermes​

运行设置向导：

hermes gateway setup

选择 BlueBubbles (iMessage)，并输入您的服务器 URL 和密码。

或直接在 ~/.hermes/.env 中设置环境变量：

BLUEBUBBLES_SERVER_URL=http://192.168.1.10:1234
BLUEBUBBLES_PASSWORD=your-server-password

4. 授权用户​

选择以下任一方式：

私聊配对（推荐）：
当有人向您的 iMessage 发送消息时，Hermes 会自动发送一个配对码。通过以下命令批准：

hermes pairing approve bluebubbles <CODE>

使用 hermes pairing list 查看待处理的配对码和已授权用户。

预先授权特定用户（在 ~/.hermes/.env 中配置）：

BLUEBUBBLES_ALLOWED_USERS=user@icloud.com,+15551234567

开放访问权限（在 ~/.hermes/.env 中配置）：

BLUEBUBBLES_ALLOW_ALL_USERS=true

5. 启动网关​

hermes gateway run

Hermes 将连接到您的 BlueBubbles 服务器，注册 webhook，并开始监听 iMessage 消息。

工作原理​

iMessage → Messages.app → BlueBubbles Server → Webhook → Hermes
Hermes → BlueBubbles REST API → Messages.app → iMessage
  • 入站消息：当新消息到达时，BlueBubbles 会通过 webhook 事件通知本地监听器。无需轮询 —— 实时送达。
  • 出站消息：Hermes 通过 BlueBubbles REST API 发送消息。
  • 媒体支持：图片、语音消息、视频和文档在双向传输中均受支持。入站附件会被下载并本地缓存，供代理处理。

环境变量​

变量是否必需默认值说明
BLUEBUBBLES_SERVER_URL是—BlueBubbles 服务器 URL
BLUEBUBBLES_PASSWORD是—服务器密码
BLUEBUBBLES_WEBHOOK_HOST否127.0.0.1Webhook 监听绑定地址
BLUEBUBBLES_WEBHOOK_PORT否8645Webhook 监听端口
BLUEBUBBLES_WEBHOOK_PATH否/bluebubbles-webhookWebhook URL 路径
BLUEBUBBLES_HOME_CHANNEL否—用于定时任务推送的电话号码/邮箱
BLUEBUBBLES_ALLOWED_USERS否—逗号分隔的授权用户列表
BLUEBUBBLES_ALLOW_ALL_USERS否false允许所有用户访问
BLUEBUBBLES_SEND_READ_RECEIPTS否true自动标记消息为已读

功能特性​

文本消息​

收发 iMessage 消息。Markdown 会自动去除，以纯文本形式发送，保持清晰简洁。

富媒体支持​

  • 图片：照片将以原生方式出现在 iMessage 对话中
  • 语音消息：音频文件以 iMessage 语音消息形式发送
  • 视频：支持视频附件
  • 文档：文件作为 iMessage 附件发送

滑动回复（Tapback 反应）​

支持“喜欢”、“赞”、“不赞”、“笑”、“强调”、“疑问”等反应。需启用 BlueBubbles 私有 API 辅助工具。

输入状态提示​

代理处理消息时，对话中会显示“正在输入...”。需启用私有 API。

已读回执​

消息处理完成后自动标记为已读。需启用私有 API。

聊天地址引用​

您可以通过邮箱或电话号码直接引用聊天对象 —— Hermes 会自动将其解析为 BlueBubbles 的聊天 GUID，无需手动使用原始 GUID 格式。

私有 API​

部分功能需要使用 BlueBubbles 私有 API 辅助工具：

  • 滑动回复（Tapback）
  • 输入状态提示
  • 已读回执
  • 通过地址创建新聊天

未启用私有 API 时，基础的文本消息和媒体功能仍可正常使用。

故障排除​

“无法连接到服务器”​

  • 确认服务器 URL 正确且 Mac 处于开机状态
  • 检查 BlueBubbles Server 是否正在运行
  • 确保网络连通性（防火墙、端口转发等）

消息未送达​

  • 检查 BlueBubbles Server → 设置 → API → Webhooks 中是否已注册 webhook
  • 确认 webhook URL 可从 Mac 访问
  • 查看 hermes logs gateway 中的 webhook 错误日志（或使用 hermes logs -f 实时追踪）

“私有 API 辅助工具未连接”​

  • 安装私有 API 辅助工具：docs.bluebubbles.app
  • 基础消息功能无需该工具即可使用 —— 仅滑动回复、输入状态和已读回执需要它