OpenClaw Matrix presentation metadata

Matrix has no native buttons, so OpenClaw does something different from the other channels: it sends a normal message with a plain-text body and attaches a structured presentation object that an OpenClaw-aware client can render as buttons, selects and context rows. Here is the event content, the fallback rules that keep every other client working, the supported blocks, how interactions round-trip, and the two rules about approvals and media.

The event content

• OpenClaw attaches normalised message presentation metadata to outbound room message events under an OpenClaw presentation content key; stock Matrix clients keep rendering the plain text body, and OpenClaw-aware clients can read the structured metadata and render native UI such as buttons, selects, context rows and dividers.
• The example is a select-model message whose body lists the choices as plain lines and whose presentation carries a version of one, the message-presentation type, an info tone, a title and a select block with a placeholder and an option whose value is a model command with the session flag.
• The version is the schema version, currently one, and the type is a stable discriminator that is always message-presentation; the Matrix adapter only emits payloads with exactly this version and type, and clients should likewise ignore unknown versions they cannot safely interpret, unknown type values and unknown block types.
• Title and tone, from info, success, warning, danger and neutral, are optional hints, and buttons and select options can carry a typed action, a command with its slash command or a callback with its value, alongside the legacy string value, with the action preferred when both are present.

The structured metadata is additive and must not be required for basic Matrix interoperability.

The fallback

OpenClaw always renders a readable plain-text fallback into the body, and the structured metadata is additive and must never be required for basic interoperability. The rendering rules are fixed: title, text and context content render as plain lines; buttons with a command action render as the label followed by the command so it stays copyable, buttons with a callback action or only a legacy value render label-only so opaque callback values stay private, disabled buttons are always label-only, and URL and web-app buttons render as the label and the address; select blocks render the placeholder, or an options heading, plus label-only option lines; and when nothing renders, for a divider-only presentation, the body falls back to three dashes. Unsupported clients keep showing the fallback text, and aware clients may prefer the structured metadata for display while preserving the fallback for copy, search, notifications and accessibility.

Blocks, interactions, approvals, media

• The Matrix outbound adapter advertises native support for buttons, select, context and divider blocks, text blocks are always supported through the fallback body, and all blocks are best-effort presentation hints, so unknown fields and block types are ignored rather than failing the message.
• The metadata adds no Matrix callback semantics: button and select values are fallback interaction payloads, usually slash or text commands, so a client that wants interaction resolves the control value, the action command first, then the action value, then the legacy value, and sends it back to the room as a normal message, for instance a model command with the session flag sent as an encrypted text message in the same room, where the explicit session flag prevents a configured-default update regardless of the model selection scope.
• Approval prompts use the dedicated approval metadata key because approvals carry safety-sensitive state, decisions and exec or plugin details, and a client that finds both keys on one event should prefer the approval renderer; when a reply contains several media URLs OpenClaw sends one event per URL with the caption and the presentation on the first event only, the same rule applies when long text is chunked across events, and presentation metadata is kept compact with large text staying in the body.

OpenClaw on Matrix is the channel post this metadata belongs to, and OpenClaw Matrix rich messages the other native surfaces the adapter offers.

A message first, a widget second

Designing the body as the source of truth and the metadata as a hint is what lets one message serve Element, a screen reader and an OpenClaw-aware client at once, and why a button click is just a command typed back into the room. OpenClaw Telegram rich messages and approvals shows the inline-keyboard approach on Telegram, where the platform does own the buttons, and OpenClaw exec approvals the approval flow that gets its own metadata here.

On Diali

Matrix is on Diali’s connectable list, alongside WhatsApp, Telegram, Discord, Slack, Mattermost, SMS and voice: the homeserver account and the room allowlist are yours, the Gateway is ours. Hosted OpenClaw on Diali is the assistant and Diali security describes the boundary that applies to each connected channel.

• Version one, type message-presentation, everything else ignorable.
• Commands stay copyable in the fallback; callback values stay private.
• Metadata rides on the first event; approvals have their own key.