Подання повідомлень

• текстові секції
• короткий контекстний текст або текст нижнього колонтитула
• розділювачі
• кнопки
• меню вибору
• заголовок і тон картки

​

Контракт

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" запускає нативну slash-команду через шлях команд ядра. Використовуйте це для вбудованих командних кнопок і меню.
• action.type: "callback" передає непрозорі дані плагіна через шлях взаємодії каналу. Плагіни каналів не повинні переінтерпретовувати callback-дані як slash-команди.
• value — це застаріле непрозоре callback-значення. Нові елементи керування мають використовувати action, щоб плагіни каналів могли зіставляти команди й callback-и без здогадок за текстом.
• url — це кнопка-посилання. Вона може існувати без value.
• webApp описує нативну для каналу кнопку вебзастосунку. Telegram відтворює її як web_app і підтримує лише в приватних чатах. web_app досі приймається у вільних JSON-навантаженнях для сумісності, але TypeScript-продюсери мають використовувати webApp.
• label є обов’язковим і також використовується в текстовому fallback.
• style має рекомендаційний характер. Рендерери мають зіставляти непідтримувані стилі з безпечним значенням за замовчуванням, а не провалювати надсилання.
• priority є необов’язковим. Коли канал оголошує обмеження дій і елементи керування потрібно відкинути, ядро спочатку зберігає кнопки з вищим пріоритетом і зберігає початковий порядок серед кнопок з однаковим пріоритетом. Коли всі елементи керування вміщуються, зберігається авторський порядок.
• disabled є необов’язковим. Канали мають явно підтримати це через supportsDisabled; інакше ядро знижує disabled-елемент керування до неінтерактивного fallback-тексту.
• reusable є необов’язковим. Канали, що підтримують повторно використовувані нативні callback-и, можуть залишати дію доступною після успішної взаємодії. Використовуйте це для повторюваних або ідемпотентних дій, як-от оновлення, перегляд або докладніші відомості; залишайте невстановленим для звичайних одноразових затверджень і деструктивних дій.

• options[].action має те саме значення command/callback, що й кнопковий action.
• options[].value — це застаріле вибране значення застосунку.
• placeholder має рекомендаційний характер і може ігноруватися каналами без нативної підтримки вибору.
• Якщо канал не підтримує вибори, fallback-текст перелічує мітки.

​

Приклади продюсерів

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

​

Контракт рендерера

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;
    };
  };
};

​

Потік рендерингу ядра

1. Нормалізує навантаження представлення.
2. Визначає вихідний адаптер цільового каналу.
3. Читає presentationCapabilities.
4. Застосовує загальні обмеження можливостей, як-от кількість дій, довжина мітки та кількість варіантів вибору, коли адаптер їх оголошує.
5. Викликає renderPresentation, коли адаптер може відрендерити навантаження.
6. Переходить до консервативного текстового fallback, коли адаптера немає або він не може рендерити.
7. Надсилає отримане навантаження через звичайний шлях доставки каналу.
8. Застосовує метадані доставки, як-от delivery.pin, після першого успішно надісланого повідомлення.

​

Правила деградації

• title як перший рядок
• блоки text як звичайні абзаци
• блоки context як компактні контекстні рядки
• блоки divider як візуальний розділювач
• мітки кнопок, зокрема URL для кнопок-посилань
• мітки варіантів вибору

​

Видимість fallback для значень кнопок

• Дії з типом command рендеряться як label: \command“, щоб користувачі могли скопіювати команду й запустити її вручну у введенні каналу.
• Дії з типом callback і застарілі поля value рендеряться лише як мітка. Непрозоре callback-значення не розкривається у fallback-тексті.
• Кнопки url / webApp рендерять текст URL поруч із міткою кнопки, оскільки URL призначений для користувача.
• Варіанти вибору рендеряться лише як мітка. Базове значення варіанта не розкривається у fallback-тексті.

• Telegram з вимкненими inline-кнопками надсилає текстовий fallback.
• Канал без підтримки вибору перелічує варіанти вибору як текст.
• Кнопка лише з URL стає або нативною кнопкою-посиланням, або fallback-рядком URL.
• Необов’язкові помилки закріплення не провалюють доставлене повідомлення.

​

Зіставлення провайдерів

​

Presentation проти InteractiveReply

• текст
• кнопки
• вибори

• заголовок
• тон
• контекст
• розділювач
• кнопки лише з URL
• загальні метадані доставки через ReplyPayload.delivery

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

• використовуйте buildApprovalPresentationFromActionDescriptors(...) замість buildApprovalInteractiveReplyFromActionDescriptors(...)
• використовуйте buildApprovalPresentation(...) замість buildApprovalInteractiveReply(...)
• використовуйте buildExecApprovalPresentation(...) замість buildExecApprovalInteractiveReply(...)

​

Закріплення доставки

• pin: true закріплює перше успішно доставлене повідомлення.
• pin.notify за замовчуванням має значення false.
• pin.required за замовчуванням має значення false.
• Необов’язкові збої закріплення деградують і залишають надіслане повідомлення без змін.
• Обов’язкові збої закріплення спричиняють збій доставки.
• Поділені на частини повідомлення закріплюють першу доставлену частину, а не останню.

​

Контрольний список автора Plugin

• Оголошуйте presentation з describeMessageTool(...), коли канал може рендерити або безпечно деградувати семантичну presentation.
• Додайте presentationCapabilities до runtime-адаптера вихідних повідомлень.
• Реалізуйте renderPresentation у runtime-коді, а не в коді налаштування control-plane Plugin.
• Не допускайте нативні UI-бібліотеки до гарячих шляхів setup/catalog.
• Оголошуйте загальні обмеження можливостей у presentationCapabilities.limits, коли вони відомі.
• Зберігайте фінальні обмеження платформи в рендерері та тестах.
• Додайте fallback-тести для непідтримуваних кнопок, виборів, URL-кнопок, дублювання заголовка/тексту та змішаних надсилань message плюс presentation.
• Додайте підтримку закріплення доставки через deliveryCapabilities.pin і pinDeliveredMessage лише тоді, коли provider може закріпити id надісланого повідомлення.
• Не відкривайте нові provider-native поля картки/блока/компонента/кнопки через спільну схему дій повідомлення.

​

Пов’язані документи

• Message CLI
• Огляд Plugin SDK
• Архітектура Plugin
• План рефакторингу presentation каналів