---
read_when:
    - ساخت کلاینت‌های Matrix که پاسخ‌های غنی OpenClaw را رندر می‌کنند
    - اشکال‌زدایی محتوای رویداد `com.openclaw.presentation`
summary: فرادادهٔ Matrix MessagePresentation برای کلاینت‌های سازگار با OpenClaw
title: فرادادهٔ نمایش ماتریس
x-i18n:
    generated_at: "2026-05-10T19:23:14Z"
    model: gpt-5.5
    provider: openai
    source_hash: c89979b6007faaa6af44c7f2511f354b96f163bcd3d5e7f99c405b51c4950537
    source_path: channels/matrix-presentation.md
    workflow: 16
---

OpenClaw می‌تواند فرادادهٔ نرمال‌سازی‌شدهٔ `MessagePresentation` را به رویدادهای خروجی Matrix `m.room.message` زیر `com.openclaw.presentation` پیوست کند.

کلاینت‌های استاندارد Matrix همچنان متن سادهٔ `body` را رندر می‌کنند. کلاینت‌های آگاه از OpenClaw می‌توانند فرادادهٔ ساختاریافته را بخوانند و UI بومی مانند دکمه‌ها، انتخاب‌گرها، ردیف‌های زمینه و جداکننده‌ها را رندر کنند.

## محتوای رویداد

فراداده در محتوای رویداد Matrix ذخیره می‌شود:

```json
{
  "msgtype": "m.text",
  "body": "Select model\n\n- DeepSeek: /model deepseek/deepseek-chat",
  "com.openclaw.presentation": {
    "version": 1,
    "type": "message.presentation",
    "title": "Select model",
    "tone": "info",
    "blocks": [
      {
        "type": "select",
        "placeholder": "Choose model",
        "options": [
          {
            "label": "DeepSeek",
            "value": "/model deepseek/deepseek-chat"
          }
        ]
      }
    ]
  }
}
```

`version` نسخهٔ طرح‌وارهٔ فرادادهٔ ارائهٔ Matrix است. `type` یک تفکیک‌گر پایدار برای کلاینت‌های آگاه از OpenClaw است. کلاینت‌ها باید مقدارهای ناشناختهٔ `type`، نسخه‌های ناشناخته‌ای را که نمی‌توانند با اطمینان تفسیر کنند، و انواع بلوک ناشناخته را نادیده بگیرند.

## رفتار جایگزین

OpenClaw همیشه یک متن جایگزین خوانا را در `body` رندر می‌کند. فرادادهٔ ساختاریافته افزایشی است و نباید برای تعامل‌پذیری پایه با Matrix لازم باشد.

کلاینت‌های پشتیبانی‌نشده باید همچنان متن جایگزین را نشان دهند. کلاینت‌های آگاه از OpenClaw می‌توانند برای نمایش، فرادادهٔ ساختاریافته را ترجیح دهند و هم‌زمان متن جایگزین را برای کپی، جست‌وجو، اعلان‌ها و دسترس‌پذیری حفظ کنند.

## بلوک‌های پشتیبانی‌شده

آداپتور خروجی Matrix پشتیبانی از موارد زیر را اعلام می‌کند:

- `buttons`
- `select`
- `context`
- `divider`

کلاینت‌ها باید این بلوک‌ها را به‌عنوان راهنمایی‌های ارائهٔ best-effort در نظر بگیرند. فیلدهای ناشناخته و انواع بلوک ناشناخته باید نادیده گرفته شوند، نه اینکه باعث شکست رندر کل پیام شوند.

## تعامل‌ها

این فراداده معناشناسی callback در Matrix اضافه نمی‌کند. مقدارهای گزینهٔ دکمه و انتخاب‌گر، payloadهای تعامل جایگزین هستند، معمولاً دستورهای اسلش یا دستورهای متنی. یک کلاینت Matrix که می‌خواهد از تعامل پشتیبانی کند، می‌تواند مقدار انتخاب‌شده را به‌عنوان یک پیام عادی به اتاق بفرستد.

برای مثال، دکمه‌ای با مقدار `/model deepseek/deepseek-chat` را می‌توان با ارسال همان مقدار به‌عنوان یک پیام متنی رمزگذاری‌شدهٔ Matrix در همان اتاق مدیریت کرد.

## رابطه با فرادادهٔ تأیید

`com.openclaw.presentation` برای ارائهٔ عمومی پیام‌های غنی است.

درخواست‌های تأیید از فرادادهٔ اختصاصی `com.openclaw.approval` استفاده می‌کنند، چون تأییدها وضعیت حساس از نظر ایمنی، تصمیم‌ها و جزئیات exec/plugin را حمل می‌کنند. اگر هر دو کلید فراداده روی یک رویداد وجود داشته باشند، کلاینت‌ها باید رندرکنندهٔ اختصاصی تأیید را ترجیح دهند.

## پیام‌های رسانه‌ای

وقتی یک پاسخ شامل چند URL رسانه‌ای باشد، OpenClaw برای هر URL رسانه‌ای یک رویداد Matrix ارسال می‌کند. فرادادهٔ ارائه فقط به نخستین رویداد رسانه‌ای پیوست می‌شود تا کلاینت‌ها یک payload ساختاریافتهٔ پایدار داشته باشند و از رندرکننده‌های تکراری جلوگیری شود.

فرادادهٔ ارائه را فشرده نگه دارید. متن بزرگِ قابل مشاهده برای کاربر باید در `body` بماند و از مسیر عادی قطعه‌بندی متن Matrix استفاده کند.