From 7d7c0b1dfe47baf8d7ff5181db8a146b8203c951 Mon Sep 17 00:00:00 2001 From: Vincent Koc Date: Tue, 21 Apr 2026 13:04:12 -0700 Subject: [PATCH] docs: cover BB tapback fallback, iMessage/SMS routing, Mattermost streaming, Matrix mention-prefixed slash --- docs/channels/bluebubbles.md | 6 +++++- docs/channels/matrix.md | 6 ++++++ docs/channels/mattermost.md | 25 +++++++++++++++++++++++++ docs/concepts/streaming.md | 16 +++++++++++----- 4 files changed, 47 insertions(+), 6 deletions(-) diff --git a/docs/channels/bluebubbles.md b/docs/channels/bluebubbles.md index e347b9b006a..cbad7bbb251 100644 --- a/docs/channels/bluebubbles.md +++ b/docs/channels/bluebubbles.md @@ -363,7 +363,7 @@ BlueBubbles supports advanced message actions when enabled in config: Available actions: -- **react**: Add/remove tapback reactions (`messageId`, `emoji`, `remove`) +- **react**: Add/remove tapback reactions (`messageId`, `emoji`, `remove`). iMessage's native tapback set is `love`, `like`, `dislike`, `laugh`, `emphasize`, and `question`. When an agent picks an emoji outside that set (for example `👀`), the reaction tool falls back to `love` so the tapback still renders instead of failing the whole request. Configured ack reactions still validate strictly and error on unknown values. - **edit**: Edit a sent message (`messageId`, `text`) - **unsend**: Unsend a message (`messageId`) - **reply**: Reply to a specific message (`messageId`, `text`, `to`) @@ -554,6 +554,10 @@ Prefer `chat_guid` for stable routing: - Direct handles: `+15555550123`, `user@example.com` - If a direct handle does not have an existing DM chat, OpenClaw will create one via `POST /api/v1/chat/new`. This requires the BlueBubbles Private API to be enabled. +### iMessage vs SMS routing + +When the same handle has both an iMessage and an SMS chat on the Mac (for example a phone number that is iMessage-registered but has also received green-bubble fallbacks), OpenClaw prefers the iMessage chat and never silently downgrades to SMS. To force the SMS chat, use an explicit `sms:` target prefix (for example `sms:+15555550123`). Handles without a matching iMessage chat still send through whatever chat BlueBubbles reports. + ## Security - Webhook requests are authenticated by comparing `guid`/`password` query params or headers against `channels.bluebubbles.password`. diff --git a/docs/channels/matrix.md b/docs/channels/matrix.md index 27b1c09f04b..80f275e2719 100644 --- a/docs/channels/matrix.md +++ b/docs/channels/matrix.md @@ -884,6 +884,12 @@ Per-account override: Related docs: [Exec approvals](/tools/exec-approvals) +## Slash commands + +Matrix slash commands (for example `/new`, `/reset`, `/model`) work directly in DMs. In rooms, OpenClaw also recognizes slash commands that are prefixed with the bot's own Matrix mention, so `@bot:server /new` triggers the command path without needing a custom mention regex. This keeps the bot responsive to room-style `@mention /command` posts that Element and similar clients emit when a user tab-completes the bot before typing the command. + +Authorization rules still apply: command senders must satisfy DM or room allowlist/owner policies just like plain messages. + ## Multi-account ```json5 diff --git a/docs/channels/mattermost.md b/docs/channels/mattermost.md index 3aacf2230d2..2ee0c52492e 100644 --- a/docs/channels/mattermost.md +++ b/docs/channels/mattermost.md @@ -244,6 +244,31 @@ Notes: - Retries apply to transient failures such as rate limits, 5xx responses, and network or timeout errors. - 4xx client errors other than `429` are treated as permanent and are not retried. +## Preview streaming + +Mattermost streams thinking, tool activity, and partial reply text into a single **draft preview post** that finalizes in place when the final answer is safe to send. The preview updates on the same post id instead of spamming the channel with per-chunk messages. + +Enable via `channels.mattermost.streaming`: + +```json5 +{ + channels: { + mattermost: { + streaming: "partial", // off | partial | block | progress + }, + }, +} +``` + +Notes: + +- `partial` is the usual choice: one preview post that is edited as the reply grows, then finalized with the complete answer. +- `block` uses append-style draft chunks inside the preview post. +- `progress` shows a status preview while generating and only posts the final answer at completion. +- `off` disables preview streaming. +- If the stream cannot be finalized in place (for example the post was deleted mid-stream), OpenClaw falls back to sending a fresh final post so the reply is never lost. +- See [Streaming](/concepts/streaming#preview-streaming-modes) for the channel-mapping matrix. + ## Reactions (message tool) - Use `message action=react` with `channel=mattermost`. diff --git a/docs/concepts/streaming.md b/docs/concepts/streaming.md index 5711ffa85d5..6ca30fff4eb 100644 --- a/docs/concepts/streaming.md +++ b/docs/concepts/streaming.md @@ -118,11 +118,12 @@ Modes: ### Channel mapping -| Channel | `off` | `partial` | `block` | `progress` | -| -------- | ----- | --------- | ------- | ----------------- | -| Telegram | ✅ | ✅ | ✅ | maps to `partial` | -| Discord | ✅ | ✅ | ✅ | maps to `partial` | -| Slack | ✅ | ✅ | ✅ | ✅ | +| Channel | `off` | `partial` | `block` | `progress` | +| ---------- | ----- | --------- | ------- | ----------------- | +| Telegram | ✅ | ✅ | ✅ | maps to `partial` | +| Discord | ✅ | ✅ | ✅ | maps to `partial` | +| Slack | ✅ | ✅ | ✅ | ✅ | +| Mattermost | ✅ | ✅ | ✅ | ✅ | Slack-only: @@ -155,6 +156,11 @@ Slack: - `block` uses append-style draft previews. - `progress` uses status preview text, then final answer. +Mattermost: + +- Streams thinking, tool activity, and partial reply text into a single draft preview post that finalizes in place when the final answer is safe to send. +- Falls back to sending a fresh final post if the preview post was deleted or is otherwise unavailable at finalize time. + ## Related - [Messages](/concepts/messages) — message lifecycle and delivery