Presentación de mensajes

​

Contrato

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: "chart";
      chartType: "pie";
      title: string;
      segments: Array<{ label: string; value: number }>;
    }
  | {
      type: "chart";
      chartType: "bar" | "area" | "line";
      title: string;
      categories: string[];
      series: Array<{ name: string; values: number[] }>;
      xLabel?: string;
      yLabel?: string;
    }
  | {
      type: "table";
      caption: string;
      headers: string[];
      rows: Array<Array<string | number>>;
      rowHeaderColumnIndex?: number;
    };

type MessagePresentationAction =
  | { type: "command"; command: string }
  | { type: "callback"; value: string }
  | {
      type: "approval";
      approvalId: string;
      approvalKind: "exec" | "plugin";
      decision: "allow-once" | "allow-always" | "deny";
    }
  | {
      type: "question";
      questionId: string;
      optionValue: string;
    }
  | { type: "url"; url: string }
  | {
      type: "web-app";
      url: string;
      widgetId?: string;
    }
  | {
      type: "web-app";
      url?: string;
      widgetId: string;
    };

type MessagePresentationButton = {
  label: string;
  action?: MessagePresentationAction;
  /** Valor de devolución de llamada heredado. Para controles nuevos, prefiera action. */
  value?: string;
  /** @deprecated Utilice una acción con el tipo "url". */
  url?: string;
  /** @deprecated Utilice una acción con el tipo "web-app". */
  webApp?: { url: string };
  /** @deprecated Utilice una acción con el tipo "web-app". */
  web_app?: { url: string };
  priority?: number;
  disabled?: boolean;
  reusable?: boolean;
  style?: "primary" | "secondary" | "success" | "danger";
};

type MessagePresentationOption = {
  label: string;
  action?: Extract<MessagePresentationAction, { type: "command" | "callback" }>;
  /** Valor de devolución de llamada heredado. Para controles nuevos, prefiera action. */
  value?: string;
};

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

• action.type: "command" ejecuta un comando de barra nativo mediante la ruta de comandos del núcleo. Utilícelo para botones y menús de comandos integrados.
• action.type: "callback" transporta datos opacos del plugin mediante la ruta de interacción del canal. Los plugins de canal no deben reinterpretar los datos de devolución de llamada como comandos de barra.
• action.type: "approval" identifica una aprobación duradera del operador, su tipo explícito exec o plugin y la decisión solicitada. Los plugins de canal codifican esa acción en una devolución de llamada privada del transporte y la resuelven mediante el servicio de aprobación; no deben analizar el texto del comando /approve ni deducir el tipo a partir del ID.
• action.type: "question" identifica una opción para una pregunta ask_user activa creada por el entorno de ejecución. Al igual que approval, esta es una acción del entorno de ejecución de OpenClaw; los agentes y plugins no deben generar identificadores de preguntas. Telegram, Discord y Slack la asignan a devoluciones de llamada nativas privadas del transporte y resuelven la opción mediante el Gateway. Cuando la pregunta se responde, caduca o se cancela, esos canales editan el mensaje entregado, eliminan sus acciones y añaden el estado final. WhatsApp, Signal e iMessage representan hasta cuatro opciones de selección única como reacciones de 1️⃣ a 4️⃣. Las demás formas de pregunta se degradan a texto de etiqueta y se puede responder con una respuesta de texto sin formato.
• action.type: "url" abre un enlace normal.
• action.type: "web-app" inicia una aplicación web nativa del canal. Establezca url para una aplicación respaldada por una URL o widgetId para un widget alojado por OpenClaw cuyo mecanismo de inicio pertenece al canal; se requiere al menos uno. Cuando ambos están presentes, un canal puede preferir el inicio de su widget alojado nativo y utilizar la URL cuando ese mecanismo no esté disponible.
• value es el valor opaco heredado de devolución de llamada. Los controles nuevos deben utilizar action para que los plugins de canal puedan asignar comandos y devoluciones de llamada sin deducirlos del texto.
• url, webApp y web_app siguen aceptándose como entradas de límite obsoletas. Los normalizadores conservan estos campos para que los renderizadores puedan distinguir la semántica heredada publicada de las acciones tipadas explícitas. Los productores nuevos deben utilizar action.
• label es obligatorio y también se utiliza en la alternativa de texto.
• style es orientativo. Los renderizadores deben asignar los estilos no compatibles a un valor predeterminado seguro, no hacer que falle el envío.
• priority es opcional. Cuando un canal anuncia límites de acciones y es necesario descartar controles, el núcleo conserva primero los botones con mayor prioridad y mantiene el orden original entre los botones de igual prioridad. Cuando caben todos los controles, se conserva el orden definido por el autor.
• disabled es opcional. Los canales deben habilitarlo expresamente con supportsDisabled; de lo contrario, el núcleo degrada el control deshabilitado a texto alternativo no interactivo. Un botón deshabilitado siempre se representa únicamente mediante su etiqueta en el texto alternativo, incluso cuando contiene una acción command.
• reusable es opcional. Los canales que admiten devoluciones de llamada nativas reutilizables pueden mantener la acción disponible después de una interacción correcta. Utilícelo para acciones repetibles o idempotentes, como actualizar, inspeccionar o mostrar más detalles; déjelo sin establecer para las aprobaciones normales de un solo uso y las acciones destructivas.

• options[].action solo acepta command o callback; las acciones de aprobación y enlace son exclusivas de los botones.
• options[].value es el valor de aplicación seleccionado heredado.
• placeholder es orientativo y los canales sin compatibilidad nativa con selecciones pueden ignorarlo.
• Si un canal no admite selecciones, el texto alternativo enumera las etiquetas.

• pie requiere valores de segmento positivos.
• bar, area y line utilizan una matriz categories ordenada. Cada serie proporciona exactamente un valor finito por categoría, en el mismo orden.
• Las etiquetas de las categorías y los nombres de las series deben ser únicos. Los bloques de gráficos no válidos o incompletos se descartan durante la normalización en lugar de modificar silenciosamente los datos.
• La representación nativa de gráficos se habilita expresamente mediante presentationCapabilities.charts. Los demás canales reciben el título del gráfico, los ejes, las categorías, las series y los valores como texto determinista. Esta es también la alternativa de accesibilidad.

• caption es un encabezado breve obligatorio. headers debe contener al menos una etiqueta de columna única y no vacía.
• rows debe contener al menos una fila. Cada fila debe tener exactamente una celda por encabezado y cada celda debe ser una cadena no vacía o un número finito.
• rowHeaderColumnIndex es un índice opcional de base cero que identifica la columna cuyas celdas deben exponerse como encabezados de fila mediante los renderizadores nativos.
• La normalización de tablas es atómica. Un título, encabezado, ancho de fila, celda o índice de encabezado de fila no válido provoca que se descarte el bloque de tabla, en lugar de truncar o reparar sus datos.
• La representación nativa de tablas se habilita expresamente mediante presentationCapabilities.tables. Los demás canales reciben el título y cada fila como texto lineal determinista, con los espacios internos contraídos:
  Pipeline abierto (tabla)
  - Cuenta: Acme; Etapa: Ganada; ARR: 125000
  - Cuenta: Globex; Etapa: Revisión; ARR: 82000
  

​

Ejemplos de productores

{
  "title": "Aprobación del despliegue",
  "tone": "warning",
  "blocks": [
    { "type": "text", "text": "La versión canary está lista para promoverse." },
    { "type": "context", "text": "Compilación 1234; la fase de staging se completó correctamente." },
    {
      "type": "buttons",
      "buttons": [
        {
          "label": "Aprobar",
          "action": { "type": "callback", "value": "deploy:approve" },
          "style": "success"
        },
        {
          "label": "Rechazar",
          "action": { "type": "callback", "value": "deploy:decline" },
          "style": "danger"
        }
      ]
    }
  ]
}

{
  "blocks": [
    { "type": "text", "text": "Las notas de la versión están listas." },
    {
      "type": "buttons",
      "buttons": [
        {
          "label": "Abrir notas",
          "action": { "type": "url", "url": "https://example.com/release" }
        }
      ]
    }
  ]
}

{
  "blocks": [
    {
      "type": "buttons",
      "buttons": [
        {
          "label": "Iniciar",
          "action": { "type": "web-app", "url": "https://example.com/app" }
        }
      ]
    }
  ]
}

{
  "title": "Elegir entorno",
  "blocks": [
    {
      "type": "select",
      "placeholder": "Entorno",
      "options": [
        { "label": "Canary", "value": "env:canary" },
        { "label": "Producción", "value": "env:prod" }
      ]
    }
  ]
}

{
  "blocks": [
    {
      "type": "chart",
      "chartType": "line",
      "title": "Ingresos trimestrales",
      "categories": ["T1", "T2", "T3"],
      "series": [
        { "name": "Producto", "values": [120, 145, 138] },
        { "name": "Servicios", "values": [80, 95, 104] }
      ],
      "xLabel": "Trimestre",
      "yLabel": "Ingresos"
    }
  ]
}

{
  "title": "Informe del pipeline",
  "tone": "info",
  "blocks": [
    { "type": "text", "text": "Oportunidades actuales por etapa." },
    {
      "type": "table",
      "caption": "Pipeline abierto",
      "headers": ["Cuenta", "Etapa", "ARR"],
      "rows": [
        ["Acme", "Ganada", 125000],
        ["Globex", "Revisión", 82000]
      ],
      "rowHeaderColumnIndex": 0
    },
    { "type": "context", "text": "Actualizado a partir de la instantánea del CRM." }
  ]
}

openclaw message send --channel slack \
  --target channel:C123 \
  --message "Aprobación del despliegue" \
  --presentation '{"title":"Aprobación del despliegue","tone":"warning","blocks":[{"type":"text","text":"La versión canary está lista."},{"type":"buttons","buttons":[{"label":"Aprobar","value":"deploy:approve","style":"success"},{"label":"Rechazar","value":"deploy:decline","style":"danger"}]}]}'

openclaw message send --channel telegram \
  --target -1001234567890 \
  --message "Tema abierto" \
  --pin

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

​

Contrato del renderizador

const adapter: ChannelOutboundAdapter = {
  deliveryMode: "direct",
  presentationCapabilities: {
    supported: true,
    buttons: true,
    selects: true,
    context: true,
    divider: true,
    charts: false,
    tables: false,
    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;
  charts?: boolean;
  tables?: 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;
    };
  };
};

​

Flujo de renderizado del núcleo

1. Normaliza la carga útil de presentación.
2. Resuelve el adaptador de salida del canal de destino.
3. Lee presentationCapabilities.
4. Aplica límites genéricos de capacidad, como el número de acciones, la longitud de las etiquetas y el número de opciones de selección, cuando el adaptador los anuncia. Los bloques de gráficos y tablas se convierten en texto determinista, salvo que el adaptador anuncie explícitamente charts: true o tables: true, respectivamente.
5. Llama a renderPresentation cuando el adaptador puede renderizar la carga útil.
6. Recurre a texto conservador cuando el adaptador no existe o no puede renderizar.
7. Envía la carga útil resultante mediante la ruta normal de entrega del canal.
8. Aplica metadatos de entrega como delivery.pin después del primer mensaje enviado correctamente.

​

Reglas de degradación

• title como primera línea
• bloques text como párrafos normales
• bloques context como líneas de contexto compactas
• bloques divider como separador visual
• etiquetas de botones, incluidas las URL de los botones de enlace
• etiquetas de opciones de selección
• título, tipo, ejes, categorías, series y valores del gráfico
• leyenda, encabezados y valores de todas las filas de la tabla

​

Visibilidad alternativa de los valores de botones

• Las acciones de tipo command se renderizan como label: `command` para que los usuarios puedan copiar el comando y ejecutarlo manualmente en la entrada del canal.
• Las acciones de tipo callback y los campos value heredados se renderizan solo con la etiqueta. El valor opaco de devolución de llamada no se expone en el texto alternativo.
• Las acciones de tipo approval se renderizan solo con la etiqueta. Los identificadores y las decisiones de aprobación son datos de transporte y no se exponen mediante ayudantes escalares genéricos ni texto alternativo.
• Las acciones url, las acciones web-app respaldadas por URL y las entradas obsoletas url / webApp / web_app renderizan el texto de la URL junto a la etiqueta del botón, ya que la URL es visible para el usuario. Las acciones exclusivas de widgets alojados se renderizan solo con la etiqueta en canales sin inicio nativo de widgets.
• Las opciones de selección se renderizan solo con la etiqueta. El valor subyacente de la opción no se expone en el texto alternativo.

• Telegram con los botones insertados deshabilitados envía texto alternativo.
• Un canal sin compatibilidad con selecciones muestra las opciones de selección como texto.
• Un canal sin compatibilidad nativa con gráficos muestra los datos del gráfico como texto.
• Un canal sin compatibilidad nativa con tablas muestra todas las filas de la tabla como texto.
• Un botón que solo contiene una URL se convierte en un botón de enlace nativo o en una línea de URL alternativa.
• Los fallos opcionales de fijación no provocan el fallo del mensaje entregado.

​

Asignación de proveedores

​

Presentación frente a InteractiveReply

• texto
• botones
• selecciones

• título
• tono
• contexto
• divisor
• gráfico
• tabla
• botones que solo contienen URL
• metadatos genéricos de entrega mediante ReplyPayload.delivery

import {
  adaptMessagePresentationForChannel,
  applyPresentationActionLimits,
  hasMessagePresentationBlocks,
  interactiveReplyToPresentation,
  isMessagePresentationInteractiveBlock,
  normalizeMessagePresentation,
  presentationPageSize,
  presentationToInteractiveControlsReply,
  presentationToInteractiveReply,
  renderMessagePresentationChartFallbackText,
  renderMessagePresentationFallbackText,
  renderMessagePresentationTableFallbackText,
  resolveMessagePresentationActionValue,
  resolveMessagePresentationButtonAction,
  resolveMessagePresentationControlValue,
  resolveMessagePresentationOptionAction,
} from "openclaw/plugin-sdk/interactive-runtime";

• normalizeMessagePresentation(raw) / hasMessagePresentationBlocks(value) validan y convierten una carga sin tipar (por ejemplo, JSON de la opción --presentation de la CLI) en MessagePresentation.
• isMessagePresentationInteractiveBlock(block) restringe un bloque a la unión buttons | select.
• resolveMessagePresentationButtonAction(button) y resolveMessagePresentationOptionAction(option) devuelven la acción tipada canónica a la vez que aceptan campos de límite obsoletos. Un valor action explícito siempre tiene prioridad.
• resolveMessagePresentationActionValue(action) / resolveMessagePresentationControlValue(control) solo leen valores escalares de comandos/devoluciones de llamada. Una acción canónica no escalar nunca pasa a un valor value heredado en segundo plano, por lo que los identificadores de aprobación y los destinos de los enlaces permanecen tipados.
• renderMessagePresentationChartFallbackText(block) / renderMessagePresentationTableFallbackText(block) representan un bloque de datos estructurados como texto determinista para las rutas de respaldo específicas del canal.

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

• use buildApprovalPresentation(...) en lugar de buildApprovalInteractiveReply(...)
• use buildExecApprovalPresentation(...) en lugar de buildExecApprovalInteractiveReply(...)

​

Fijación en la entrega

• pin: true fija el primer mensaje entregado correctamente.
• pin.notify tiene como valor predeterminado false.
• pin.required tiene como valor predeterminado false.
• Los fallos de fijación opcional se degradan y dejan intacto el mensaje enviado.
• Los fallos de fijación obligatoria hacen que la entrega falle.
• Los mensajes fragmentados fijan el primer fragmento entregado, no el último.

​

Lista de comprobación para autores de plugins

• Declare presentation desde describeMessageTool(...) cuando el canal pueda representar o degradar de forma segura la presentación semántica.
• Añada presentationCapabilities al adaptador de salida en tiempo de ejecución.
• Implemente renderPresentation en el código de tiempo de ejecución, no en el código de configuración del plugin del plano de control.
• Mantenga las bibliotecas de interfaz de usuario nativas fuera de las rutas críticas de configuración/catálogo.
• Declare límites genéricos de capacidad en presentationCapabilities.limits cuando se conozcan.
• Conserve los límites finales de la plataforma en el representador y las pruebas.
• Añada pruebas de respaldo para gráficos, tablas, botones, selectores y botones de URL no compatibles, duplicación de título/texto y envíos mixtos de message más presentation.
• Añada compatibilidad con la fijación en la entrega mediante deliveryCapabilities.pin y pinDeliveredMessage solo cuando el proveedor pueda fijar el identificador del mensaje enviado.
• No exponga nuevos campos de tarjetas/bloques/componentes/botones nativos del proveedor mediante el esquema compartido de acciones de mensaje.

​

Documentación relacionada

• CLI de mensajes
• Descripción general del SDK de plugins
• Arquitectura de plugins
• Plan de refactorización de la presentación de canales