Nachrichtendarstellung

• Textabschnitte
• kleiner Kontext-/Footer-Text
• Trennlinien
• Buttons
• Auswahlmenüs
• Kartentitel und Ton

​

Contract

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

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 MessagePresentationAction =
  | { type: "command"; command: string }
  | { type: "callback"; value: string };

type MessagePresentationButton = {
  label: string;
  action?: MessagePresentationAction;
  /** Legacy callback value. Prefer action for new controls. */
  value?: string;
  url?: string;
  webApp?: { url: string };
  /** @deprecated Use webApp. Accepted for legacy JSON payloads only. */
  web_app?: { url: string };
  priority?: number;
  disabled?: boolean;
  reusable?: boolean;
  style?: "primary" | "secondary" | "success" | "danger";
};

type MessagePresentationOption = {
  label: string;
  action?: MessagePresentationAction;
  /** Legacy callback value. Prefer action for new controls. */
  value?: string;
};

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

• action.type: "command" führt einen nativen Slash-Befehl über den Befehlspfad des Core aus. Verwenden Sie dies für integrierte Befehls-Buttons und Menüs.
• action.type: "callback" transportiert opake Plugin-Daten über den Interaktionspfad des Channels. Channel-Plugins dürfen Callback-Daten nicht als Slash-Befehle neu interpretieren.
• value ist der veraltete opake Callback-Wert. Neue Controls sollten action verwenden, damit Channel-Plugins Befehle und Callbacks zuordnen können, ohne aus Text raten zu müssen.
• url ist ein Link-Button. Er kann ohne value existieren.
• webApp beschreibt einen channel-nativen Web-App-Button. Telegram rendert dies als web_app und unterstützt es nur in privaten Chats. web_app wird aus Kompatibilitätsgründen weiterhin in lockeren JSON-Payloads akzeptiert, TypeScript-Produzenten sollten jedoch webApp verwenden.
• label ist erforderlich und wird auch im Text-Fallback verwendet.
• style ist beratend. Renderer sollten nicht unterstützte Styles auf einen sicheren Standard abbilden, nicht den Versand fehlschlagen lassen.
• priority ist optional. Wenn ein Channel Aktionslimits angibt und Controls verworfen werden müssen, behält Core zuerst Buttons mit höherer Priorität bei und bewahrt die ursprüngliche Reihenfolge unter Buttons gleicher Priorität. Wenn alle Controls passen, bleibt die authored Reihenfolge erhalten.
• disabled ist optional. Channels müssen sich mit supportsDisabled dafür anmelden; andernfalls stuft Core das deaktivierte Control auf nicht interaktiven Fallback-Text zurück.
• reusable ist optional. Channels, die wiederverwendbare native Callbacks unterstützen, können die Aktion nach einer erfolgreichen Interaktion verfügbar halten. Verwenden Sie dies für wiederholbare oder idempotente Aktionen wie Aktualisieren, Inspizieren oder weitere Details; lassen Sie es für normale einmalige Approvals und destruktive Aktionen unset.

• options[].action hat dieselbe Befehls-/Callback-Bedeutung wie Button-action.
• options[].value ist der veraltete ausgewählte Anwendungswert.
• placeholder ist beratend und kann von Channels ohne native Select-Unterstützung ignoriert werden.
• Wenn ein Channel Selects nicht unterstützt, listet Fallback-Text die Labels auf.

​

Producer-Beispiele

{
  "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" }
      ]
    }
  ]
}

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

{
  "blocks": [
    {
      "type": "buttons",
      "buttons": [{ "label": "Launch", "web_app": { "url": "https://example.com/app" } }]
    }
  ]
}

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

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"}]}]}'

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

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

​

Renderer-Contract

const adapter: ChannelOutboundAdapter = {
  deliveryMode: "direct",
  presentationCapabilities: {
    supported: true,
    buttons: true,
    selects: true,
    context: true,
    divider: true,
    limits: {
      actions: {
        maxActions: 25,
        maxActionsPerRow: 5,
        maxRows: 5,
        maxLabelLength: 80,
        maxValueBytes: 100,
        supportsStyles: true,
        supportsDisabled: false,
      },
      selects: {
        maxOptions: 25,
        maxLabelLength: 100,
        maxValueBytes: 100,
      },
      text: {
        maxLength: 2000,
        encoding: "characters",
        markdownDialect: "discord-markdown",
      },
    },
  },
  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 });
  },
};

type ChannelPresentationCapabilities = {
  supported?: boolean;
  buttons?: boolean;
  selects?: boolean;
  context?: boolean;
  divider?: boolean;
  limits?: {
    actions?: {
      maxActions?: number;
      maxActionsPerRow?: number;
      maxRows?: number;
      maxLabelLength?: number;
      maxValueBytes?: number;
      supportsStyles?: boolean;
      supportsDisabled?: boolean;
      supportsLayoutHints?: boolean;
    };
    selects?: {
      maxOptions?: number;
      maxLabelLength?: number;
      maxValueBytes?: number;
    };
    text?: {
      maxLength?: number;
      encoding?: "characters" | "utf8-bytes" | "utf16-units";
      markdownDialect?: "plain" | "markdown" | "html" | "slack-mrkdwn" | "discord-markdown";
      supportsEdit?: boolean;
    };
  };
};

​

Core-Render-Flow

1. Normalisiert den Presentation-Payload.
2. Löst den ausgehenden Adapter des Ziel-Channels auf.
3. Liest presentationCapabilities.
4. Wendet generische Capability-Limits wie Aktionsanzahl, Label-Länge und Anzahl der Select-Optionen an, wenn der Adapter sie angibt.
5. Ruft renderPresentation auf, wenn der Adapter den Payload rendern kann.
6. Fällt auf konservativen Text zurück, wenn der Adapter fehlt oder nicht rendern kann.
7. Sendet den resultierenden Payload über den normalen Zustellungspfad des Channels.
8. Wendet Zustellungsmetadaten wie delivery.pin nach der ersten erfolgreich gesendeten Nachricht an.

​

Degradationsregeln

• title als erste Zeile
• text-Blöcke als normale Absätze
• context-Blöcke als kompakte Kontextzeilen
• divider-Blöcke als visueller Trenner
• Button-Labels, einschließlich URLs für Link-Buttons
• Labels von Select-Optionen

​

Fallback-Sichtbarkeit von Button-Werten

• command-typisierte Aktionen rendern als label: \command“, sodass Benutzer den Befehl kopieren und manuell in der Channel-Eingabe ausführen können.
• callback-typisierte Aktionen und veraltete value-Felder rendern nur als Label. Der opake Callback-Wert wird im Fallback-Text nicht offengelegt.
• url / webApp-Buttons rendern den URL-Text zusammen mit dem Button-Label, da die URL benutzerseitig sichtbar ist.
• Select-Optionen rendern nur als Label. Der zugrunde liegende Optionswert wird im Fallback-Text nicht offengelegt.

• Telegram mit deaktivierten Inline-Buttons sendet Text-Fallback.
• Ein Channel ohne Select-Unterstützung listet Select-Optionen als Text auf.
• Ein Nur-URL-Button wird entweder zu einem nativen Link-Button oder zu einer Fallback-URL-Zeile.
• Optionale Pin-Fehler lassen die zugestellte Nachricht nicht fehlschlagen.

​

Provider-Zuordnung

​

Presentation vs InteractiveReply

• Text
• Buttons
• Selects

• Titel
• Ton
• Kontext
• Trenner
• reine URL-Buttons
• generische Zustellungsmetadaten über ReplyPayload.delivery

• InteractiveReply, InteractiveReplyBlock, InteractiveReplyButton, InteractiveReplyOption, InteractiveReplySelectBlock und InteractiveReplyTextBlock
• normalizeInteractiveReply(...)
• hasInteractiveReplyBlocks(...)
• interactiveReplyToPresentation(...)
• presentationToInteractiveReply(...)
• presentationToInteractiveControlsReply(...)
• resolveInteractiveTextFallback(...)
• reduceInteractiveReply(...)

• Verwenden Sie buildApprovalPresentationFromActionDescriptors(...) anstelle von buildApprovalInteractiveReplyFromActionDescriptors(...)
• Verwenden Sie buildApprovalPresentation(...) anstelle von buildApprovalInteractiveReply(...)
• Verwenden Sie buildExecApprovalPresentation(...) anstelle von buildExecApprovalInteractiveReply(...)

​

Zustellungs-Pin

• pin: true heftet die erste erfolgreich zugestellte Nachricht an.
• pin.notify ist standardmäßig false.
• pin.required ist standardmäßig false.
• Optionale Pin-Fehler werden reduziert und lassen die gesendete Nachricht intakt.
• Erforderliche Pin-Fehler lassen die Zustellung fehlschlagen.
• Aufgeteilte Nachrichten heften den ersten zugestellten Abschnitt an, nicht den letzten Abschnitt.

​

Checkliste für Plugin-Autoren

• Deklarieren Sie presentation aus describeMessageTool(...), wenn der Kanal semantische Presentation rendern oder sicher reduzieren kann.
• Fügen Sie presentationCapabilities zum Runtime-Outbound-Adapter hinzu.
• Implementieren Sie renderPresentation im Runtime-Code, nicht im Control-Plane-Plugin- Setup-Code.
• Halten Sie native UI-Bibliotheken aus heißen Setup-/Katalogpfaden heraus.
• Deklarieren Sie generische Fähigkeitslimits unter presentationCapabilities.limits, wenn sie bekannt sind.
• Bewahren Sie endgültige Plattformlimits im Renderer und in Tests.
• Fügen Sie Fallback-Tests für nicht unterstützte Buttons, Selects, URL-Buttons, Titel/Text- Duplizierung und gemischte Sends aus message plus presentation hinzu.
• Fügen Sie Unterstützung für Zustellungs-Pins über deliveryCapabilities.pin und pinDeliveredMessage nur hinzu, wenn der Provider die gesendete Nachrichten-ID anheften kann.
• Legen Sie keine neuen provider-nativen Karten-/Block-/Komponenten-/Button-Felder über das gemeinsam genutzte Nachrichtenaktionsschema offen.

​

Verwandte Dokumentation

• Message-CLI
• Plugin-SDK-Überblick
• Plugin-Architektur
• Refaktorierungsplan für Kanal-Presentation