playbooks

home / skills / openclaw / skills / bluebubbles

bluebubbles skill

/skills/kevin19830331/bluebubbles

This skill helps you build and update the BlueBubbles channel plugin for Clawdbot, handling REST, webhooks, and runtime integration.

npx playbooks add skill openclaw/skills --skill bluebubbles

Review the files below or copy the command above to add this skill to your agents.

Files (2)
SKILL.md
2.2 KB
---
name: bluebubbles
description: Build or update the BlueBubbles external channel plugin for Clawdbot (extension package, REST send/probe, webhook inbound).
---

# 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.
- `sendMessageBlueBubbles` in `extensions/bluebubbles/src/send.ts` for text delivery.
- `resolveChatGuidForTarget` in `extensions/bluebubbles/src/send.ts` for chat lookup.
- `sendBlueBubblesReaction` in `extensions/bluebubbles/src/reactions.ts` for tapbacks.
- `sendBlueBubblesTyping` + `markBlueBubblesChatRead` in `extensions/bluebubbles/src/chat.ts`.
- `downloadBlueBubblesAttachment` in `extensions/bluebubbles/src/attachments.ts` for inbound media.
- `buildBlueBubblesApiUrl` + `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: `action=react target=+15551234567 messageId=ABC123 emoji=❤️`

Overview

This skill helps you build or update the BlueBubbles external channel plugin for Clawdbot. It packages the extension, implements REST send/probe endpoints, and handles inbound webhooks so BlueBubbles can route messages, attachments, typing, and reactions into Clawdbot.

How this skill works

The skill wires an extension under extensions/bluebubbles with channel, send, probe, reactions, attachments, runtime bridge, and webhook monitor modules. It uses internal helpers for health checks, message delivery, reaction and typing actions, and shared REST plumbing to talk to the BlueBubbles server and normalize webhook payloads into the core plugin runtime.

When to use it

  • Implementing or updating BlueBubbles channel support in Clawdbot
  • Adding or fixing webhook inbound handling for BlueBubbles gateway payloads
  • Building REST send/probe endpoints and reliable fetch/timeouts for BlueBubbles
  • Supporting attachments, stickers, tapbacks, typing, and read receipts
  • Onboarding BlueBubbles into the channel catalog and runtime

Best practices

  • Use provided helpers (probeBlueBubbles, sendMessageBlueBubbles, etc.) instead of raw API calls to keep behavior consistent
  • Normalize sender and chat IDs defensively; BlueBubbles payloads vary by version
  • Skip messages from self and route all inbound events through api.runtime into the core reply pipeline
  • Represent inbound media with <media:...> placeholders when text is empty and include MediaUrl(s) in the inbound context
  • Gate actions (reactions, typing) behind config flags and honor channels.bluebubbles.* settings for serverUrl, password, and webhookPath

Example use cases

  • Add a probe endpoint that verifies BlueBubbles server health using probeBlueBubbles
  • Implement message sending that resolves chat GUIDs and calls sendMessageBlueBubbles with retries
  • Handle webhook POSTs: normalize IDs, ignore self messages, attach media via downloadBlueBubblesAttachment
  • Support react action requiring both target and messageId, and forward to sendBlueBubblesReaction
  • Expose typing and read actions using sendBlueBubblesTyping and markBlueBubblesChatRead

FAQ

How should I handle attachments sent via webhook?

When the webhook delivers attachments, download them with downloadBlueBubblesAttachment, insert a <media:...> placeholder if text is empty, and add MediaUrl(s) to the inbound context so the core pipeline can process files.

What config keys control BlueBubbles behavior?

Core settings include channels.bluebubbles.serverUrl, channels.bluebubbles.password, and channels.bluebubbles.webhookPath. Action gating like reactions is controlled by channels.bluebubbles.actions.reactions.

How do I send a reaction to a message?

Use the react action with both a target (phone or chat ID) and messageId, for example: action=react target=+15551234567 messageId=ABC123 emoji=❤️, which maps to sendBlueBubblesReaction.