BlueBubbles plugin
Use this skill when working on the BlueBubbles channel plugin.
Layout
- - Extension package:
extensions/bluebubbles/ (entry: index.ts). - Channel implementation:
extensions/bluebubbles/src/channel.ts. - Webhook handling:
extensions/bluebubbles/src/monitor.ts (register via api.registerHttpHandler). - REST helpers:
extensions/bluebubbles/src/send.ts + extensions/bluebubbles/src/probe.ts. - Runtime bridge:
extensions/bluebubbles/src/runtime.ts (set via api.runtime). - Catalog entry for onboarding:
src/channels/plugins/catalog.ts.
Internal helpers (use these, not raw API calls)
- -
probeBlueBubbles in extensions/bluebubbles/src/probe.ts for health checks. - INLINECODE12 in
extensions/bluebubbles/src/send.ts for text delivery. - INLINECODE14 in
extensions/bluebubbles/src/send.ts for chat lookup. - INLINECODE16 in
extensions/bluebubbles/src/reactions.ts for tapbacks. - INLINECODE18 +
markBlueBubblesChatRead in extensions/bluebubbles/src/chat.ts. - INLINECODE21 in
extensions/bluebubbles/src/attachments.ts for inbound media. - INLINECODE23 +
blueBubblesFetchWithTimeout in extensions/bluebubbles/src/types.ts for shared REST plumbing.
Webhooks
- - BlueBubbles posts JSON to the gateway HTTP server.
- Normalize sender/chat IDs defensively (payloads vary by version).
- Skip messages marked as from self.
- Route into core reply pipeline via the plugin runtime (
api.runtime) and clawdbot/plugin-sdk helpers. - For attachments/stickers, use
<media:...> placeholders when text is empty and attach media paths via MediaUrl(s) in the inbound context.
Config (core)
- -
channels.bluebubbles.serverUrl (base URL), channels.bluebubbles.password, channels.bluebubbles.webhookPath. - Action gating:
channels.bluebubbles.actions.reactions (default true).
Message tool notes
- - Reactions: The
react action requires a target (phone number or chat identifier) in addition to messageId. Example: INLINECODE37
BlueBubbles 插件
在处理 BlueBubbles 频道插件时使用此技能。
布局
- - 扩展包：extensions/bluebubbles/（入口：index.ts）。
- 频道实现：extensions/bluebubbles/src/channel.ts。
- Webhook 处理：extensions/bluebubbles/src/monitor.ts（通过 api.registerHttpHandler 注册）。
- REST 辅助工具：extensions/bluebubbles/src/send.ts + extensions/bluebubbles/src/probe.ts。
- 运行时桥接：extensions/bluebubbles/src/runtime.ts（通过 api.runtime 设置）。
- 入门引导的目录条目：src/channels/plugins/catalog.ts。
内部辅助工具（使用这些，而非原始 API 调用）
- - extensions/bluebubbles/src/probe.ts 中的 probeBlueBubbles，用于健康检查。
- extensions/bluebubbles/src/send.ts 中的 sendMessageBlueBubbles，用于文本发送。
- extensions/bluebubbles/src/send.ts 中的 resolveChatGuidForTarget，用于聊天查找。
- extensions/bluebubbles/src/reactions.ts 中的 sendBlueBubblesReaction，用于点按回复。
- extensions/bluebubbles/src/chat.ts 中的 sendBlueBubblesTyping + markBlueBubblesChatRead。
- extensions/bluebubbles/src/attachments.ts 中的 downloadBlueBubblesAttachment，用于接收媒体。
- extensions/bluebubbles/src/types.ts 中的 buildBlueBubblesApiUrl + blueBubblesFetchWithTimeout，用于共享 REST 基础设施。
Webhook
- - BlueBubbles 将 JSON 数据发送到网关 HTTP 服务器。
- 防御性地标准化发送者/聊天 ID（负载因版本而异）。
- 跳过标记为来自自身的消息。
- 通过插件运行时（api.runtime）和 clawdbot/plugin-sdk 辅助工具路由到核心回复管道。
- 对于附件/贴纸，当文本为空时使用 占位符，并通过入站上下文中的 MediaUrl(s) 附加媒体路径。
配置（核心）
- - channels.bluebubbles.serverUrl（基础 URL）、channels.bluebubbles.password、channels.bluebubbles.webhookPath。
- 操作控制：channels.bluebubbles.actions.reactions（默认为 true）。
消息工具说明
- - 反应： react 操作除了 messageId 外，还需要 target（电话号码或聊天标识符）。示例：action=react target=+15551234567 messageId=ABC123 emoji=❤️
