---
read_when:
    - ساخت کلاینت‌های Matrix برای رندر پاسخ‌های غنی OpenClaw
    - اشکال‌زدایی محتوای رویداد com.openclaw.presentation
summary: فرادادهٔ MessagePresentation در Matrix برای کلاینت‌های سازگار با OpenClaw
title: فرادادهٔ ارائهٔ Matrix
x-i18n:
    generated_at: "2026-07-27T14:53:18Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    prompt_version: 32
    provider: openai
    source_hash: c0de4d13c6cefc6f91dcc7a4b0edeea6bf001f3bd71f52c9f0498ad422783d8a
    source_path: channels/matrix-presentation.md
    workflow: 16
---

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

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

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

```json
{
  "msgtype": "m.text",
  "body": "مدل را انتخاب کنید\n\nمدل را برگزینید:\n- DeepSeek",
  "com.openclaw.presentation": {
    "version": 1,
    "type": "message.presentation",
    "title": "مدل را انتخاب کنید",
    "tone": "info",
    "blocks": [
      {
        "type": "select",
        "placeholder": "مدل را برگزینید",
        "options": [
          {
            "label": "DeepSeek",
            "value": "/model deepseek/deepseek-chat"
          }
        ]
      }
    ]
  }
}
```

- `version` نسخهٔ طرح‌وارهٔ فراداده است؛ نسخهٔ فعلی `1` است. `type` یک ممیز پایدار است و همیشه `"message.presentation"` خواهد بود. آداپتور Matrix فقط بارهایی را منتشر می‌کند که دقیقاً همین نسخه و نوع را دارند؛ کلاینت‌ها نیز باید نسخه‌های ناشناخته‌ای را که نمی‌توانند با اطمینان تفسیر کنند، مقادیر ناشناختهٔ `type` و انواع بلوک ناشناخته را نادیده بگیرند.
- `title` و `tone` ‏(`info`، `success`، `warning`، `danger`، `neutral`) راهنماهای اختیاری هستند.
- دکمه‌ها و گزینه‌های انتخاب می‌توانند در کنار رشتهٔ قدیمی `value`، یک `action` نوع‌دار (`{ "type": "command", "command": "/..." }` یا `{ "type": "callback", "value": "..." }`) داشته باشند. وقتی هر دو موجودند، `action` را ترجیح دهید.

## رفتار بازگشتی

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

قواعد رندر حالت بازگشتی:

- محتوای `title`، `text` و `context` به‌شکل خطوط ساده رندر می‌شود.
- دکمه‌هایی با کنش `command` به‌شکل ``label: `/command` `` رندر می‌شوند تا فرمان قابل کپی‌کردن بماند. دکمه‌هایی با کنش `callback` یا فقط مقدار قدیمی `value` تنها با برچسب رندر می‌شوند تا مقادیر مبهم بازفراخوانی خصوصی بمانند؛ دکمه‌های غیرفعال همیشه فقط با برچسب رندر می‌شوند. دکمه‌های URL و برنامهٔ وب به‌شکل `label: URL` رندر می‌شوند.
- بلوک‌های انتخاب، متن جای‌نما (یا `Options:`) را به‌عنوان عنوان و سپس خطوط گزینه‌ها را تنها با برچسب رندر می‌کنند.
- اگر چیزی رندر نشود، برای مثال در نمایشی که فقط جداکننده دارد، بدنه به `---` بازمی‌گردد.

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

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

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

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

بلوک‌های `text` همیشه از طریق بدنهٔ بازگشتی پشتیبانی می‌شوند. همهٔ بلوک‌ها را راهنماهای نمایشی با بیشترین تلاش ممکن در نظر بگیرید؛ به‌جای ناموفق‌کردن کل پیام، فیلدها و انواع بلوک ناشناخته را نادیده بگیرید.

## تعاملات

این فراداده معنای بازفراخوانی Matrix را اضافه نمی‌کند. مقادیر دکمه و انتخاب، بارهای تعامل بازگشتی هستند که معمولاً فرمان‌های اسلش‌دار یا فرمان‌های متنی‌اند. کلاینت Matrix که می‌خواهد از تعامل پشتیبانی کند، مقدار کنترل را (`action.command`، سپس `action.value` و بعد `value`) تعیین می‌کند و آن را به‌صورت یک پیام عادی به اتاق بازمی‌فرستد.

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

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

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

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

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

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

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