संदेश प्रस्तुति

• टेक्स्ट सेक्शन
• छोटा संदर्भ/फुटर टेक्स्ट
• डिवाइडर
• बटन
• चयन मेनू
• कार्ड शीर्षक और टोन

​

अनुबंध

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" core के command path के माध्यम से native slash command चलाता है। built-in command buttons और menus के लिए इसका उपयोग करें।
• action.type: "callback" channel के interaction path के माध्यम से opaque plugin data ले जाता है। Channel plugins को callback data को slash commands के रूप में दोबारा व्याख्यायित नहीं करना चाहिए।
• value legacy opaque callback value है। नए controls को action का उपयोग करना चाहिए ताकि channel plugins text से अनुमान लगाए बिना commands और callbacks को map कर सकें।
• url एक link button है। यह value के बिना मौजूद हो सकता है।
• webApp channel-native web app button का वर्णन करता है। Telegram इसे web_app के रूप में render करता है और केवल private chats में इसका समर्थन करता है। compatibility के लिए loose JSON payloads में web_app अभी भी स्वीकार किया जाता है, लेकिन TypeScript producers को webApp का उपयोग करना चाहिए।
• label आवश्यक है और text fallback में भी उपयोग किया जाता है।
• style advisory है। Renderers को unsupported styles को सुरक्षित default पर map करना चाहिए, send को fail नहीं करना चाहिए।
• priority वैकल्पिक है। जब कोई channel action limits advertise करता है और controls को हटाना पड़ता है, core पहले उच्च-priority buttons रखता है और समान priority वाले buttons के बीच मूल क्रम संरक्षित करता है। जब सभी controls fit होते हैं, authored order संरक्षित रहता है।
• disabled वैकल्पिक है। Channels को supportsDisabled के साथ opt in करना होगा; अन्यथा core disabled control को non-interactive fallback text में degrade करता है।
• reusable वैकल्पिक है। वे channels जो reusable native callbacks का समर्थन करते हैं, सफल interaction के बाद action को उपलब्ध रख सकते हैं। refresh, inspect, या अधिक details जैसी repeatable या idempotent actions के लिए इसका उपयोग करें; normal one-shot approvals और destructive actions के लिए इसे unset छोड़ें।

• options[].action का command/callback अर्थ button action जैसा ही है।
• options[].value legacy selected application value है।
• placeholder advisory है और native select support के बिना channels द्वारा अनदेखा किया जा सकता है।
• यदि कोई channel selects का समर्थन नहीं करता, fallback text labels की सूची दिखाता है।

​

Producer उदाहरण

{
  "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 अनुबंध

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. presentation payload को normalize करता है।
2. target channel के outbound adapter को resolve करता है।
3. presentationCapabilities पढ़ता है।
4. adapter द्वारा advertise किए जाने पर action count, label length, और select option count जैसी generic capability limits लागू करता है।
5. जब adapter payload को render कर सकता है, renderPresentation call करता है।
6. adapter अनुपस्थित होने या render न कर पाने पर conservative text पर fallback करता है।
7. resulting payload को normal channel delivery path के माध्यम से भेजता है।
8. पहली सफल sent message के बाद delivery.pin जैसी delivery metadata लागू करता है।

​

Degradation rules

• पहली line के रूप में title
• normal paragraphs के रूप में text blocks
• compact context lines के रूप में context blocks
• visual separator के रूप में divider blocks
• button labels, link buttons के URLs सहित
• select option labels

• inline buttons disabled होने पर Telegram text fallback भेजता है।
• select support के बिना कोई channel select options को text के रूप में सूचीबद्ध करता है।
• केवल-URL button या तो native link button बनता है या fallback URL line।
• वैकल्पिक pin failures delivered message को fail नहीं करते।

​

Provider mapping

​

प्रस्तुति बनाम InteractiveReply

• टेक्स्ट
• बटन
• चयन

• शीर्षक
• टोन
• संदर्भ
• विभाजक
• केवल-URL बटन
• ReplyPayload.delivery के माध्यम से सामान्य डिलीवरी मेटाडेटा

import {
  adaptMessagePresentationForChannel,
  applyPresentationActionLimits,
  interactiveReplyToPresentation,
  normalizeMessagePresentation,
  presentationPageSize,
  presentationToInteractiveControlsReply,
  presentationToInteractiveReply,
  renderMessagePresentationFallbackText,
} from "openclaw/plugin-sdk/interactive-runtime";

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

• buildApprovalInteractiveReplyFromActionDescriptors(...) के बजाय buildApprovalPresentationFromActionDescriptors(...) उपयोग करें
• buildApprovalInteractiveReply(...) के बजाय buildApprovalPresentation(...) उपयोग करें
• buildExecApprovalInteractiveReply(...) के बजाय buildExecApprovalPresentation(...) उपयोग करें

​

डिलीवरी पिन

• pin: true पहले सफलतापूर्वक डिलीवर किए गए संदेश को पिन करता है।
• pin.notify का डिफ़ॉल्ट false है।
• pin.required का डिफ़ॉल्ट false है।
• वैकल्पिक पिन विफलताएं घटकर रह जाती हैं और भेजे गए संदेश को यथावत छोड़ती हैं।
• आवश्यक पिन विफलताएं डिलीवरी को विफल करती हैं।
• खंडित संदेश पहले डिलीवर किए गए खंड को पिन करते हैं, अंतिम खंड को नहीं।

​

Plugin लेखक चेकलिस्ट

• जब चैनल अर्थपूर्ण प्रस्तुति को रेंडर कर सकता हो या सुरक्षित रूप से घटा सकता हो, तब describeMessageTool(...) से presentation घोषित करें।
• रनटाइम आउटबाउंड एडेप्टर में presentationCapabilities जोड़ें।
• रनटाइम कोड में renderPresentation लागू करें, कंट्रोल-प्लेन Plugin सेटअप कोड में नहीं।
• नेटिव UI लाइब्रेरी को हॉट सेटअप/कैटलॉग पथों से बाहर रखें।
• ज्ञात होने पर presentationCapabilities.limits पर सामान्य क्षमता सीमाएं घोषित करें।
• रेंडरर और परीक्षणों में अंतिम प्लेटफ़ॉर्म सीमाएं सुरक्षित रखें।
• असमर्थित बटन, चयन, URL बटन, शीर्षक/टेक्स्ट डुप्लिकेशन, और मिश्रित message प्लस presentation भेजने के लिए फ़ॉलबैक परीक्षण जोड़ें।
• deliveryCapabilities.pin और pinDeliveredMessage के माध्यम से डिलीवरी पिन समर्थन केवल तभी जोड़ें जब प्रदाता भेजे गए संदेश id को पिन कर सके।
• साझा संदेश क्रिया स्कीमा के माध्यम से नए प्रदाता-नेटिव कार्ड/ब्लॉक/कंपोनेंट/बटन फ़ील्ड उजागर न करें।

​

संबंधित दस्तावेज़

• संदेश CLI
• Plugin SDK अवलोकन
• Plugin आर्किटेक्चर
• चैनल प्रस्तुति रीफ़ैक्टर योजना