df7464ddf6
* fix(bluebubbles): include sender identity in group chat envelopes Use formatInboundEnvelope (matching iMessage/Signal pattern) so group messages show the group label in the envelope header and include the sender name in the message body. ConversationLabel now resolves to the group name for groups instead of being undefined. Fixes #16210 Co-authored-by: zerone0x <hi@trine.dev> * fix(bluebubbles): use finalizeInboundContext and set BodyForAgent to raw text Wrap ctxPayload with finalizeInboundContext (matching iMessage/Signal/ every other channel) so field normalization, ChatType, ConversationLabel fallback, and MediaType alignment are applied consistently. Change BodyForAgent from the envelope-formatted body to rawBody so the agent prompt receives clean message text instead of the [BlueBubbles ...] envelope wrapper. Co-authored-by: zerone0x <hi@trine.dev> * docs: add changelog entry for BlueBubbles group sender fix (#16326) * fix(bluebubbles): include id in fromLabel matching formatInboundFromLabel Align fromLabel output with the shared formatInboundFromLabel pattern: groups get 'GroupName id:peerId', DMs get 'Name id:senderId' when the name differs from the id. Addresses PR review feedback. Co-authored-by: zerone0x <hi@trine.dev> --------- Co-authored-by: zerone0x <hi@trine.dev>
BlueBubbles extension (developer reference)
This directory contains the BlueBubbles external channel plugin for OpenClaw.
If you’re looking for how to use BlueBubbles as an agent/tool user, see:
skills/bluebubbles/SKILL.md
Layout
- Extension package:
extensions/bluebubbles/(entry:index.ts). - Channel implementation:
extensions/bluebubbles/src/channel.ts. - Webhook handling:
extensions/bluebubbles/src/monitor.ts(register viaapi.registerHttpHandler). - REST helpers:
extensions/bluebubbles/src/send.ts+extensions/bluebubbles/src/probe.ts. - Runtime bridge:
extensions/bluebubbles/src/runtime.ts(set viaapi.runtime). - Catalog entry for onboarding:
src/channels/plugins/catalog.ts.
Internal helpers (use these, not raw API calls)
probeBlueBubblesinextensions/bluebubbles/src/probe.tsfor health checks.sendMessageBlueBubblesinextensions/bluebubbles/src/send.tsfor text delivery.resolveChatGuidForTargetinextensions/bluebubbles/src/send.tsfor chat lookup.sendBlueBubblesReactioninextensions/bluebubbles/src/reactions.tsfor tapbacks.sendBlueBubblesTyping+markBlueBubblesChatReadinextensions/bluebubbles/src/chat.ts.downloadBlueBubblesAttachmentinextensions/bluebubbles/src/attachments.tsfor inbound media.buildBlueBubblesApiUrl+blueBubblesFetchWithTimeoutinextensions/bluebubbles/src/types.tsfor 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) andopenclaw/plugin-sdkhelpers. - For attachments/stickers, use
<media:...>placeholders when text is empty and attach media paths viaMediaUrl(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
reactaction requires atarget(phone number or chat identifier) in addition tomessageId. Example:action=react target=+15551234567 messageId=ABC123 emoji=❤️