iMessage 详细配置

1. 前置准备

需要一台运行 macOS 的设备，并已登录 iMessage 账号。需要安装并运行 BlueBubbles Server（bluebubbles.app）。BlueBubbles 负责与 iMessage 通信，Semibot 通过 HTTP API 与 BlueBubbles 交互。

2. 在 Semibot 创建实例

进入 Semibot 配置中心 > Bots > 新建，选择 iMessage 类型。填写 bridgeUrl（BlueBubbles 服务地址，如 http://localhost:1234）、defaultHandle（可选，默认发送目标的手机号或邮箱）。选择默认 Agent，保存实例。

3. 配置 BlueBubbles 桥接

在 BlueBubbles Server 设置中，配置 Webhook URL 指向：http://<semibot-host>:<port>/v1/integrations/imessage/events/internal。需要在请求头中添加 x-semibot-internal-token（Runtime 内部认证令牌）。Semibot 会每 5 秒轮询 BlueBubbles 的 /health 端点检查连接状态。实例模式需设为 gateway、bridge 或 bluebubbles。出站消息通过 BlueBubbles 的 /messages/send API 发送。

4. 联调与验证

1. 确认 BlueBubbles Server 正在运行且健康检查通过。2. 在 Semibot 中点击「测试」确认出站链路可达。3. 通过 iMessage 发送消息。4. 在 Semibot 事件中心确认收到入站事件。5. 在会话详情查看执行记录和回传结果。常见错误：BlueBubbles 未运行（检查服务状态）、Webhook 未配置（检查 BlueBubbles 设置）、iMessage 未登录（检查 macOS 系统设置）。注意：iMessage 仅支持纯文本和文件附件，不支持 Markdown 和消息线程。