Message presentation

Message presentation is OpenClaw's shared contract for rich outbound chat UI. It lets agents, CLI commands, approval flows, and plugins describe the message intent once, while each channel plugin renders the best native shape it can.

Use presentation for portable message UI:

• text sections
• small context/footer text
• dividers
• buttons
• select menus
• card title and tone

Do not add new provider-native fields such as Discord

, Slack , Telegram , Teams , or Feishu to the shared message tool. Those are renderer outputs owned by the channel plugin.

Contract

Plugin authors import the public contract from:

ts
Copy
import type {
  MessagePresentation,
  ReplyPayloadDelivery,
} from "openclaw/plugin-sdk/interactive-runtime";

Shape:

ts
Copy
type MessagePresentation = {
  title?: string;
  tone?: "neutral" | "info" | "success" | "warning" | "danger";
  blocks: MessagePresentationBlock[];
};

type MessagePresentationBlock =
  | { type: "text"; text: string }
  | { type: "context"; text: string }
  | { type: "divider" }
  | { type: "buttons"; buttons: MessagePresentationButton[] }
  | { type: "select"; placeholder?: string; options: MessagePresentationOption[] };

type MessagePresentationButton = {
  label: string;
  value?: string;
  url?: string;
  style?: "primary" | "secondary" | "success" | "danger";
};

type MessagePresentationOption = {
  label: string;
  value: string;
};

type ReplyPayloadDelivery = {
  pin?:
    | boolean
    | {
        enabled: boolean;
        notify?: boolean;
        required?: boolean;
      };
};

Button semantics:

• text

  Copy

  value
  is an application action value routed back through the channel's existing interaction path when the channel supports clickable controls.
• text

  Copy

  url
  is a link button. It can exist without
  text

  Copy

  value
  .
• text

  Copy

  label
  is required and is also used in text fallback.
• text

  Copy

  style
  is advisory. Renderers should map unsupported styles to a safe default, not fail the send.

Select semantics:

• text

  Copy

  options[].value
  is the selected application value.
• text

  Copy

  placeholder
  is advisory and may be ignored by channels without native select support.
• If a channel does not support selects, fallback text lists the labels.

Producer examples

Simple card:

json
Copy
{
  "title": "Deploy approval",
  "tone": "warning",
  "blocks": [
    { "type": "text", "text": "Canary is ready to promote." },
    { "type": "context", "text": "Build 1234, staging passed." },
    {
      "type": "buttons",
      "buttons": [
        { "label": "Approve", "value": "deploy:approve", "style": "success" },
        { "label": "Decline", "value": "deploy:decline", "style": "danger" }
      ]
    }
  ]
}

URL-only link button:

json
Copy
{
  "blocks": [
    { "type": "text", "text": "Release notes are ready." },
    {
      "type": "buttons",
      "buttons": [{ "label": "Open notes", "url": "https://example.com/release" }]
    }
  ]
}

Select menu:

json
Copy
{
  "title": "Choose environment",
  "blocks": [
    {
      "type": "select",
      "placeholder": "Environment",
      "options": [
        { "label": "Canary", "value": "env:canary" },
        { "label": "Production", "value": "env:prod" }
      ]
    }
  ]
}

CLI send:

bash
Copy
openclaw message send --channel slack \
  --target channel:C123 \
  --message "Deploy approval" \
  --presentation '{"title":"Deploy approval","tone":"warning","blocks":[{"type":"text","text":"Canary is ready."},{"type":"buttons","buttons":[{"label":"Approve","value":"deploy:approve","style":"success"},{"label":"Decline","value":"deploy:decline","style":"danger"}]}]}'

Pinned delivery:

bash
Copy
openclaw message send --channel telegram \
  --target -1001234567890 \
  --message "Topic opened" \
  --pin

Pinned delivery with explicit JSON:

json
Copy
{
  "pin": {
    "enabled": true,
    "notify": true,
    "required": false
  }
}

Renderer contract

Channel plugins declare render support on their outbound adapter:

ts
Copy
const adapter: ChannelOutboundAdapter = {
  deliveryMode: "direct",
  presentationCapabilities: {
    supported: true,
    buttons: true,
    selects: true,
    context: true,
    divider: true,
  },
  deliveryCapabilities: {
    pin: true,
  },
  renderPresentation({ payload, presentation, ctx }) {
    return renderNativePayload(payload, presentation, ctx);
  },
  async pinDeliveredMessage({ target, messageId, pin }) {
    await pinNativeMessage(target, messageId, { notify: pin.notify === true });
  },
};

Capability fields are intentionally simple booleans. They describe what the renderer can make interactive, not every native platform limit. Renderers still own platform-specific limits such as maximum button count, block count, and card size.

Core render flow

When a

or message action includes , core:

1. Normalizes the presentation payload.
2. Resolves the target channel's outbound adapter.
3. Reads
   text

   Copy

   presentationCapabilities
   .
4. Calls
   text

   Copy

   renderPresentation
   when the adapter can render the payload.
5. Falls back to conservative text when the adapter is absent or cannot render.
6. Sends the resulting payload through the normal channel delivery path.
7. Applies delivery metadata such as
   text

   Copy

   delivery.pin
   after the first successful sent message.

Core owns fallback behavior so producers can stay channel-agnostic. Channel plugins own native rendering and interaction handling.

Degradation rules

Presentation must be safe to send on limited channels.

Fallback text includes:

• text

  Copy

  title
  as the first line
• text

  Copy

  text
  blocks as normal paragraphs
• text

  Copy

  context
  blocks as compact context lines
• text

  Copy

  divider
  blocks as a visual separator
• button labels, including URLs for link buttons
• select option labels

Unsupported native controls should degrade rather than fail the whole send. Examples:

• Telegram with inline buttons disabled sends text fallback.
• A channel without select support lists select options as text.
• A URL-only button becomes either a native link button or a fallback URL line.
• Optional pin failures do not fail the delivered message.

The main exception is

; if pinning is requested as required and the channel cannot pin the sent message, delivery reports failure.

Provider mapping

Current bundled renderers:

Provider-native payload compatibility is a transition affordance for existing reply producers. It is not a reason to add new shared native fields.

Presentation vs InteractiveReply

is the older internal subset used by approval and interaction helpers. It supports:

• text
• buttons
• selects

is the canonical shared send contract. It adds:

• title
• tone
• context
• divider
• URL-only buttons
• generic delivery metadata through
  text

  Copy

  ReplyPayload.delivery

Use helpers from

when bridging older code:

ts
Copy
import {
  interactiveReplyToPresentation,
  normalizeMessagePresentation,
  presentationToInteractiveReply,
  renderMessagePresentationFallbackText,
} from "openclaw/plugin-sdk/interactive-runtime";

New code should accept or produce

directly.

Delivery pin

Pinning is delivery behavior, not presentation. Use

instead of provider-native fields such as .

Semantics:

• text

  Copy

  pin: true
  pins the first successfully delivered message.
• text

  Copy

  pin.notify
  defaults to
  text

  Copy

  false
  .
• text

  Copy

  pin.required
  defaults to
  text

  Copy

  false
  .
• Optional pin failures degrade and leave the sent message intact.
• Required pin failures fail delivery.
• Chunked messages pin the first delivered chunk, not the tail chunk.

Manual

, , and message actions still exist for existing messages where the provider supports those operations.

Plugin author checklist

• Declare
  text

  Copy

  presentation
  from
  text

  Copy

  describeMessageTool(...)
  when the channel can render or safely degrade semantic presentation.
• Add
  text

  Copy

  presentationCapabilities
  to the runtime outbound adapter.
• Implement
  text

  Copy

  renderPresentation
  in runtime code, not control-plane plugin setup code.
• Keep native UI libraries out of hot setup/catalog paths.
• Preserve platform limits in the renderer and tests.
• Add fallback tests for unsupported buttons, selects, URL buttons, title/text duplication, and mixed
  text

  Copy

  message
  plus
  text

  Copy

  presentation
  sends.
• Add delivery pin support through
  text

  Copy

  deliveryCapabilities.pin
  and
  text

  Copy

  pinDeliveredMessage
  only when the provider can pin the sent message id.
• Do not expose new provider-native card/block/component/button fields through the shared message action schema.

Related docs

• Message CLI
• Plugin SDK Overview
• Plugin Architecture
• Channel Presentation Refactor Plan