Matrix MessagePresentation Metadata for OpenClaw Clients

OpenClaw writes normalized MessagePresentation metadata into outbound Matrix m.room.message events, placing it under the com.openclaw.presentation content key.

Standard Matrix clients continue to show the plain text body. Clients that understand OpenClaw can parse the structured metadata and display native elements such as buttons, selects, context rows, and dividers.

Event content

{
  "msgtype": "m.text",
  "body": "Select model\n\nChoose model:\n- DeepSeek",
  "com.openclaw.presentation": {
    "version": 1,
    "type": "message.presentation",
    "title": "Select model",
    "tone": "info",
    "blocks": [
      {
        "type": "select",
        "placeholder": "Choose model",
        "options": [
          {
            "label": "DeepSeek",
            "value": "/model deepseek/deepseek-chat -s"
          }
        ]
      }
    ]
  }
}

• version indicates the metadata schema version, currently 1. The discriminator type is stable and always set to "message.presentation". The Matrix adapter emits payloads only with this exact version and type; clients should also disregard versions they cannot interpret safely, along with unknown type values and unrecognized block types.
• The hints title and tone (info, success, warning, danger, neutral) are optional.
• Buttons and select options may include a typed action (either { "type": "command", "command": "/..." } or { "type": "callback", "value": "..." }) in addition to the older string value. When both exist, action takes precedence.

Fallback behavior

OpenClaw always places readable plain text into body as a fallback. The structured metadata is supplementary and never required for standard Matrix interoperability.

Fallback rendering rules:

• Content from title, text, and context appears as plain lines.
• Buttons with a command action show as label: `/command` so the command remains copyable. Buttons with a callback action or only an old-style value display label-only, keeping opaque callback values hidden; disabled buttons always show label-only. URL and web-app buttons appear as label: URL.
• Select blocks show the placeholder (or Options:) as a heading, followed by label-only option lines.
• When nothing renders, such as a presentation with only dividers, the body uses --- as the fallback.

Clients without OpenClaw support keep seeing the fallback text. OpenClaw-aware clients can choose the structured metadata for display while retaining the fallback for copying, searching, notifications, and accessibility.

Supported blocks

The Matrix outbound adapter declares native support for:

• buttons
• select
• context
• divider

text blocks are always handled via the fallback body. Treat every block as a best-effort presentation hint; ignore unknown fields and block types instead of rejecting the entire message.

Interactions

This metadata introduces no new Matrix callback behavior. Button and select values serve as fallback interaction payloads, typically slash commands or text commands. A Matrix client wanting to support interaction resolves the control value (action.command, then action.value, then value) and posts it back to the room as a regular message.

For instance, a button with value /model deepseek/deepseek-chat -s can be handled by sending that value as an encrypted Matrix text message in the same room. The explicit session flag prevents a configured-default update regardless of the model selection scope setting.

Relationship to approval metadata

com.openclaw.presentation covers general rich message presentation.

Approval prompts rely on the separate com.openclaw.approval metadata because approvals involve safety-sensitive state, decisions, and exec/plugin details. If both metadata keys appear on the same event, clients should favor the dedicated approval renderer.

Media messages

When a reply includes multiple media URLs, OpenClaw sends one Matrix event per URL. Caption text and presentation metadata attach only to the first event, giving clients a single stable structured payload without duplicate renderers. The same holds when long text is split across events: the metadata rides on the first event only.

Keep presentation metadata small. Large user-visible text should live in body and follow the normal Matrix text chunking path.