---
read_when:
    - ساخت کلاینت‌های Matrix که پاسخ‌های غنی OpenClaw را نمایش می‌دهند
    - اشکال‌زدایی محتوای رویداد com.openclaw.presentation
summary: فرادادهٔ MessagePresentation در Matrix برای کلاینت‌های سازگار با OpenClaw
title: فرادادهٔ نمایش Matrix
x-i18n:
    generated_at: "2026-07-12T09:39:04Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    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": "Select model\n\nChoose model:\n- DeepSeek",
  "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` نسخهٔ شِمای فراداده است؛ نسخهٔ فعلی `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` استفاده می‌کنند، زیرا تأییدها شامل وضعیت حساس به ایمنی، تصمیم‌ها و جزئیات اجرا/Plugin هستند. اگر هر دو کلید فراداده در یک رویداد وجود داشته باشند، کلاینت‌ها باید رندرکنندهٔ اختصاصی تأیید را ترجیح دهند.

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

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

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