Back to Details

bluebubbles

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

BlueBubbles Actions

BlueBubbles 操作指南

Overview

概述

BlueBubbles is OpenClaw’s recommended iMessage integration. Use the 
message
tool with 
channel: "bluebubbles"
to send messages and manage iMessage conversations: send texts and attachments, react (tapbacks), edit/unsend, reply in threads, and manage group participants/names/icons.
BlueBubbles是OpenClaw官方推荐的iMessage集成方案。你可以使用携带
channel: "bluebubbles"
参数的
message
工具发送消息、管理iMessage会话：支持发送文本和附件、添加点按回应（tapbacks）、编辑/撤回消息、在话题线程中回复，以及管理群聊的参与人员/群名称/群头像。

Inputs to collect

需收集的输入参数

  • target
    (prefer 
    chat_guid:...
    ; also 
    +15551234567
    in E.164 or 
    user@example.com
    )
  • message
    text for send/edit/reply
  • messageId
    for react/edit/unsend/reply
  • Attachment 
    path
    for local files, or 
    buffer
    + 
    filename
    for base64
If the user is vague ("text my mom"), ask for the recipient handle or chat guid and the exact message content.
  • target
    （优先使用
    chat_guid:...
    格式；也支持E.164格式的手机号如
    +15551234567
    ，或者邮箱地址如
    user@example.com
    ）
  • message
    ：发送/编辑/回复场景下的文本内容
  • messageId
    ：回应/编辑/撤回/回复场景下需要的消息ID
  • 附件参数：本地文件使用
    path
    参数，base64格式的附件使用
    buffer
    + 
    filename
    参数
如果用户表述模糊（例如“给我妈发个短信”），请向用户确认接收人标识或聊天guid，以及具体的消息内容。

Actions

操作说明

Send a message

发送消息

json
{
  "action": "send",
  "channel": "bluebubbles",
  "target": "+15551234567",
  "message": "hello from OpenClaw"
}
json
{
  "action": "send",
  "channel": "bluebubbles",
  "target": "+15551234567",
  "message": "hello from OpenClaw"
}

React (tapback)

添加点按回应（tapback）

json
{
  "action": "react",
  "channel": "bluebubbles",
  "target": "+15551234567",
  "messageId": "<message-guid>",
  "emoji": "❤️"
}
json
{
  "action": "react",
  "channel": "bluebubbles",
  "target": "+15551234567",
  "messageId": "<message-guid>",
  "emoji": "❤️"
}

Remove a reaction

移除回应

json
{
  "action": "react",
  "channel": "bluebubbles",
  "target": "+15551234567",
  "messageId": "<message-guid>",
  "emoji": "❤️",
  "remove": true
}
json
{
  "action": "react",
  "channel": "bluebubbles",
  "target": "+15551234567",
  "messageId": "<message-guid>",
  "emoji": "❤️",
  "remove": true
}

Edit a previously sent message

编辑已发送消息

json
{
  "action": "edit",
  "channel": "bluebubbles",
  "target": "+15551234567",
  "messageId": "<message-guid>",
  "message": "updated text"
}
json
{
  "action": "edit",
  "channel": "bluebubbles",
  "target": "+15551234567",
  "messageId": "<message-guid>",
  "message": "updated text"
}

Unsend a message

撤回消息

json
{
  "action": "unsend",
  "channel": "bluebubbles",
  "target": "+15551234567",
  "messageId": "<message-guid>"
}
json
{
  "action": "unsend",
  "channel": "bluebubbles",
  "target": "+15551234567",
  "messageId": "<message-guid>"
}

Reply to a specific message

回复指定消息

json
{
  "action": "reply",
  "channel": "bluebubbles",
  "target": "+15551234567",
  "replyTo": "<message-guid>",
  "message": "replying to that"
}
json
{
  "action": "reply",
  "channel": "bluebubbles",
  "target": "+15551234567",
  "replyTo": "<message-guid>",
  "message": "replying to that"
}

Send an attachment

发送附件

json
{
  "action": "sendAttachment",
  "channel": "bluebubbles",
  "target": "+15551234567",
  "path": "/tmp/photo.jpg",
  "caption": "here you go"
}
json
{
  "action": "sendAttachment",
  "channel": "bluebubbles",
  "target": "+15551234567",
  "path": "/tmp/photo.jpg",
  "caption": "here you go"
}

Send with an iMessage effect

发送带iMessage特效的消息

json
{
  "action": "sendWithEffect",
  "channel": "bluebubbles",
  "target": "+15551234567",
  "message": "big news",
  "effect": "balloons"
}
json
{
  "action": "sendWithEffect",
  "channel": "bluebubbles",
  "target": "+15551234567",
  "message": "big news",
  "effect": "balloons"
}

Notes

注意事项

  • Requires gateway config 
    channels.bluebubbles
    (serverUrl/password/webhookPath).
  • Prefer 
    chat_guid
    targets when you have them (especially for group chats).
  • BlueBubbles supports rich actions, but some are macOS-version dependent (for example, edit may be broken on macOS 26 Tahoe).
  • The gateway may expose both short and full message ids; full ids are more durable across restarts.
  • Developer reference for the underlying plugin lives in 
    extensions/bluebubbles/README.md
    .
  • 需要提前配置网关的
    channels.bluebubbles
    参数（serverUrl/密码/webhookPath）。
  • 如有
    chat_guid
    格式的目标请优先使用（尤其适用于群聊场景）。
  • BlueBubbles支持丰富的操作，但部分功能依赖macOS版本（例如编辑功能可能在macOS 26 Tahoe版本上无法正常使用）。
  • 网关可能同时返回短消息ID和完整消息ID；完整ID在服务重启后可用性更强。
  • 底层插件的开发者参考文档位于
    extensions/bluebubbles/README.md
    。

Ideas to try

可尝试的用法

  • React with a tapback to acknowledge a request.
  • Reply in-thread when a user references a specific message.
  • Send a file attachment with a short caption.
  • 发送点按回应确认收到请求。
  • 用户提及某条具体消息时，在对应线程中回复。
  • 发送附带简短说明的文件附件。