Naar hoofdinhoud gaan

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

Berichtpresentatie is het gedeelde contract van OpenClaw voor rijke uitgaande chat-UI. Hiermee kunnen agents, CLI-opdrachten, goedkeuringsflows en plugins de berichtintentie één keer beschrijven, terwijl elke kanaalplugin de best mogelijke native vorm rendert. Gebruik presentation voor draagbare bericht-UI:
  • tekstsecties
  • kleine context-/voettekst
  • scheidingslijnen
  • knoppen
  • selectiemenu’s
  • kaarttitel en toon
Voeg geen nieuwe provider-native velden toe, zoals Discord components, Slack blocks, Telegram buttons, Teams card of Feishu card, aan de gedeelde berichttool. Dit zijn rendereruitvoerwaarden die eigendom zijn van de kanaalplugin.

​
Contract

Plugin-auteurs importeren het openbare contract vanuit: 
import type {
  MessagePresentation,
  ReplyPayloadDelivery,
} from "openclaw/plugin-sdk/interactive-runtime";
Vorm: 
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;
      };
};
Knopsemantiek:
  • value is een applicatieactiewaarde die wordt teruggeleid via het bestaande interactiepad van het kanaal wanneer het kanaal klikbare besturingselementen ondersteunt.
  • url is een linkknop. Deze kan bestaan zonder value.
  • label is verplicht en wordt ook gebruikt in de tekstfallback.
  • style is adviserend. Renderers moeten niet-ondersteunde stijlen toewijzen aan een veilige standaardwaarde, niet het verzenden laten mislukken.
Selectiesemantiek:
  • options[].value is de geselecteerde applicatiewaarde.
  • placeholder is adviserend en kan worden genegeerd door kanalen zonder native selectieondersteuning.
  • Als een kanaal selecties niet ondersteunt, vermeldt fallbacktekst de labels.

​
Voorbeelden voor producenten

Eenvoudige kaart: 
{
  "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" }
      ]
    }
  ]
}
Linkknop met alleen URL: 
{
  "blocks": [
    { "type": "text", "text": "Release notes are ready." },
    {
      "type": "buttons",
      "buttons": [{ "label": "Open notes", "url": "https://example.com/release" }]
    }
  ]
}
Selectiemenu: 
{
  "title": "Choose environment",
  "blocks": [
    {
      "type": "select",
      "placeholder": "Environment",
      "options": [
        { "label": "Canary", "value": "env:canary" },
        { "label": "Production", "value": "env:prod" }
      ]
    }
  ]
}
CLI-verzending: 
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"}]}]}'
Vastgezette bezorging: 
openclaw message send --channel telegram \
  --target -1001234567890 \
  --message "Topic opened" \
  --pin
Vastgezette bezorging met expliciete JSON: 
{
  "pin": {
    "enabled": true,
    "notify": true,
    "required": false
  }
}

​
Renderercontract

Kanaalplugins declareren renderondersteuning op hun uitgaande adapter: 
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 });
  },
};
Capaciteitsvelden zijn bewust eenvoudige booleans. Ze beschrijven wat de renderer interactief kan maken, niet elke native platformlimiet. Renderers blijven eigenaar van platformspecifieke limieten, zoals het maximale aantal knoppen, het aantal blokken en de kaartgrootte.

​
Kernrenderflow

Wanneer een ReplyPayload of berichtactie presentation bevat, doet core het volgende:
  1. Normaliseert de presentatiepayload.
  2. Lost de uitgaande adapter van het doelkanaal op.
  3. Leest presentationCapabilities.
  4. Roept renderPresentation aan wanneer de adapter de payload kan renderen.
  5. Valt terug op conservatieve tekst wanneer de adapter ontbreekt of niet kan renderen.
  6. Verzendt de resulterende payload via het normale bezorgpad van het kanaal.
  7. Past bezorgmetadata zoals delivery.pin toe na het eerste succesvol verzonden bericht.
Core is eigenaar van fallbackgedrag, zodat producenten kanaalagnostisch kunnen blijven. Kanaalplugins zijn eigenaar van native rendering en interactieafhandeling.

​
Degradatieregels

Presentatie moet veilig te verzenden zijn op beperkte kanalen. Fallbacktekst bevat:
  • title als de eerste regel
  • text-blokken als normale alinea’s
  • context-blokken als compacte contextregels
  • divider-blokken als visueel scheidingsteken
  • knoplabels, inclusief URL’s voor linkknoppen
  • labels van selectieopties
Niet-ondersteunde native besturingselementen moeten degraderen in plaats van de hele verzending te laten mislukken. Voorbeelden:
  • Telegram met uitgeschakelde inlineknoppen verzendt tekstfallback.
  • Een kanaal zonder selectieondersteuning vermeldt selectieopties als tekst.
  • Een knop met alleen URL wordt een native linkknop of een fallback-URL-regel.
  • Optionele pinfouten laten het bezorgde bericht niet mislukken.
De belangrijkste uitzondering is delivery.pin.required: true; als vastzetten als verplicht is aangevraagd en het kanaal het verzonden bericht niet kan vastzetten, rapporteert bezorging een fout.

​
Providertoewijzing

Huidige gebundelde renderers:
KanaalNative renderdoelOpmerkingen
DiscordComponenten en componentcontainersBehoudt legacy channelData.discord.components voor bestaande provider-native payloadproducenten, maar nieuwe gedeelde verzendingen moeten presentation gebruiken.
SlackBlock KitBehoudt legacy channelData.slack.blocks voor bestaande provider-native payloadproducenten, maar nieuwe gedeelde verzendingen moeten presentation gebruiken.
TelegramTekst plus inline toetsenbordenKnoppen/selecties vereisen inlineknopcapaciteit voor het doeloppervlak; anders wordt tekstfallback gebruikt.
MattermostTekst plus interactieve propsAndere blokken degraderen naar tekst.
Microsoft TeamsAdaptive CardsPlatte message-tekst wordt met de kaart opgenomen wanneer beide worden opgegeven.
FeishuInteractieve kaartenKaartkop kan title gebruiken; body vermijdt duplicatie van die titel.
Gewone kanalenTekstfallbackKanalen zonder renderer krijgen nog steeds leesbare uitvoer.
Compatibiliteit met provider-native payloads is een overgangsvoorziening voor bestaande antwoordproducenten. Het is geen reden om nieuwe gedeelde native velden toe te voegen.

​
Presentation versus InteractiveReply

InteractiveReply is de oudere interne subset die wordt gebruikt door goedkeurings- en interactiehelpers. Deze ondersteunt:
  • tekst
  • knoppen
  • selecties
MessagePresentation is het canonieke gedeelde verzendcontract. Het voegt toe:
  • titel
  • toon
  • context
  • scheidingslijn
  • knoppen met alleen URL
  • generieke bezorgmetadata via ReplyPayload.delivery
Gebruik helpers uit openclaw/plugin-sdk/interactive-runtime bij het overbruggen van oudere code: 
import {
  interactiveReplyToPresentation,
  normalizeMessagePresentation,
  presentationToInteractiveReply,
  renderMessagePresentationFallbackText,
} from "openclaw/plugin-sdk/interactive-runtime";
Nieuwe code moet MessagePresentation direct accepteren of produceren.

​
Bezorgpin

Vastzetten is bezorggedrag, geen presentatie. Gebruik delivery.pin in plaats van provider-native velden zoals channelData.telegram.pin. Semantiek:
  • pin: true zet het eerste succesvol bezorgde bericht vast.
  • pin.notify heeft standaardwaarde false.
  • pin.required heeft standaardwaarde false.
  • Optionele pinfouten degraderen en laten het verzonden bericht intact.
  • Vereiste pinfouten laten bezorging mislukken.
  • Berichten in chunks zetten de eerste bezorgde chunk vast, niet de laatste chunk.
Handmatige pin-, unpin- en pins-berichtacties blijven bestaan voor bestaande berichten waar de provider die bewerkingen ondersteunt.

​
Checklist voor Plugin-auteurs

  • Declareer presentation vanuit describeMessageTool(...) wanneer het kanaal semantische presentatie kan renderen of veilig kan degraderen.
  • Voeg presentationCapabilities toe aan de uitgaande runtime-adapter.
  • Implementeer renderPresentation in runtimecode, niet in control-plane plugin- setupcode.
  • Houd native UI-bibliotheken uit hete setup-/cataloguspaden.
  • Behoud platformlimieten in de renderer en tests.
  • Voeg fallbacktests toe voor niet-ondersteunde knoppen, selecties, URL-knoppen, duplicatie van titel/tekst en gemengde verzendingen met message plus presentation.
  • Voeg ondersteuning voor bezorgpin toe via deliveryCapabilities.pin en pinDeliveredMessage alleen wanneer de provider de verzonden bericht-id kan vastzetten.
  • Stel geen nieuwe provider-native kaart-/blok-/component-/knopvelden bloot via het gedeelde schema voor berichtacties.

​
Gerelateerde docs