---
read_when:
    - در حال ساخت یا بازآرایی مسیر دریافت یک Plugin کانال پیام‌رسانی هستید
    - به ساخت مشترک زمینهٔ ورودی، ثبت نشست یا ارسال پاسخ آماده‌شده نیاز دارید
    - در حال مهاجرت راهنماهای قدیمی نوبت کانال به APIهای ورودی/پیام هستید
summary: 'کمک‌تابع‌های رویداد ورودی برای Pluginهای کانال: ساخت زمینه، هماهنگ‌سازی اجراکنندهٔ مشترک، رکورد نشست و ارسال پاسخ آماده‌شده'
title: API ورودی کانال
x-i18n:
    generated_at: "2026-07-27T14:26:04Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    prompt_version: 32
    provider: openai
    source_hash: 854408ca42cfe1e1b48e4fd223b176f438e1db28deb9a5aa33eea8238127d9df
    source_path: plugins/sdk-channel-inbound.md
    workflow: 16
---

مسیرهای دریافت کانال از یک جریان پیروی می‌کنند:

```text
رویداد پلتفرم -> واقعیت‌ها/زمینه ورودی -> پاسخ عامل -> تحویل پیام
```

برای نرمال‌سازی رویداد ورودی، قالب‌بندی، ریشه‌ها و هماهنگ‌سازی از `openclaw/plugin-sdk/channel-inbound` استفاده کنید.
برای ارسال بومی، رسید، تحویل پایدار و رفتار پیش‌نمایش زنده از
`openclaw/plugin-sdk/channel-outbound` استفاده کنید.

## کمک‌تابع‌های اصلی

```ts
import {
  buildChannelInboundEventContext,
  runChannelInboundEvent,
  dispatchChannelInboundReply,
} from "openclaw/plugin-sdk/channel-inbound";
```

- `buildChannelInboundEventContext(...)`: واقعیت‌های نرمال‌شده کانال را
  به زمینه اعلان/نشست نگاشت می‌کند. فراداده فرستنده/گفت‌وگوی تحت مالکیت کانال را
  از طریق `channelContext` عبور دهید که قلاب‌های Plugin آن را به‌صورت `ctx.channelContext` می‌بینند.
  برای فیلدهای مختص کانال، `PluginHookChannelSenderContext` یا `PluginHookChannelChatContext`
  را از این زیرمسیر تکمیل کنید.
- `runChannelInboundEvent(...)`: دریافت، طبقه‌بندی، بررسی مقدماتی، حل،
  ثبت، توزیع و نهایی‌سازی را برای یک رویداد ورودی پلتفرم اجرا می‌کند.
- `dispatchChannelInboundReply(...)`: یک پاسخ ورودی ازپیش‌ساخته‌شده را
  با یک آداپتور تحویل ثبت و توزیع می‌کند.

برای رویدادهای ورودی صرفاً رسانه‌ای، بدنه پیام و متن فرمان را خالی نگه دارید و
به‌ازای هر پیوست بومی یک واقعیت `ChannelInboundMediaInput` عبور دهید. هنگامی که یک خط
تاریخچه پیرامونی یا حامل صرفاً متنی دیگری باید آن واقعیت‌ها را توصیف کند، از
`formatMediaPlaceholderText(media)` استفاده کنید. این تابع هر واقعیت را ابتدا بر اساس `kind`، سپس نوع
MIME و بعد پسوند مسیر یا URL طبقه‌بندی می‌کند؛ پیوست‌های بومی بارگیری‌نشده نیز باید
هرکدام یک واقعیت صرفاً نوعی ایجاد کنند. از قالب‌بند برای ساخت بدنه اصلی
ورودی استفاده نکنید.

رکوردهای پیوست تحت مالکیت Plugin را با `toInboundMediaFacts(...)` نرمال‌سازی کنید، سپس
آرایه مرتب حاصل را از طریق فیلد `media` زمینه عبور دهید:

```ts
const media = toInboundMediaFacts([
  { path: saved.path, url: nativeUrl, contentType: saved.contentType, messageId },
]);

const ctx = finalizeInboundContext({ Body: caption, media });
```

موقعیت در آرایه، هویت پیوست است. `transcribed`، `messageId` و
`workspaceDir` هر واقعیت جایگزین فیلدهای قدیمی موازیِ شاخص/فضای کاری می‌شوند. فیلدهای زمینه
`MediaPath`، `MediaPaths`، `MediaUrl`، `MediaUrls`، `MediaType`، `MediaTypes`،
`MediaTranscribedIndexes`، `MediaWorkspaceDir` و `MediaStaged`،
به‌همراه `buildChannelInboundMediaPayload(...)`، فقط به‌عنوان سازگاری منسوخ‌شده
همچنان در دسترس هستند. Pluginهای جدید نباید آن‌ها را بسازند یا بخوانند.

کانال‌های همراه/بومی که از قبل شیء زمان‌اجرای تزریق‌شده Plugin را دریافت می‌کنند،
می‌توانند به‌جای واردکردن مستقیم این زیرمسیر، همان کمک‌تابع‌ها را در
`runtime.channel.inbound.*` فراخوانی کنند:

```ts
await runtime.channel.inbound.run({
  channel: "demo",
  accountId,
  raw: platformEvent,
  adapter: {
    ingest: normalizePlatformEvent,
    resolveTurn: resolveInboundReply,
  },
});
```

ورودی‌های `dispatchChannelInboundReply(...)` را برای توزیع‌کننده‌های سازگاری که
تحویل پلتفرم را در آداپتور تحویل نگه می‌دارند، سرهم کنید. مسیرهای ارسال جدید
باید به‌جای آن از آداپتورهای پیام و کمک‌تابع‌های پیام پایدارِ
`channel-outbound` استفاده کنند.

## قرارداد تسویه تحویل

`ChannelInboundTurnPlan.delivery` مالک ارسال بومی هر محموله پاسخ منطقی است.
هسته مالک ترتیب قلاب‌های خروجی و، در صورت اعلام آمادگی آداپتور،
مشاهده نهایی `message_sent` است. این مسئولیت‌ها را جدا نگه دارید تا
یک محموله نتواند رویدادهای نهایی تکراری ایجاد کند.

فیلدهای نتیجه تحویل معانی زیر را دارند:

| فیلد                    | قرارداد                                                                                                                                                                                                                     |
| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `content`                | متن قابل‌مشاهده پذیرفته‌شده توسط ارائه‌دهنده برای محموله منطقی پس از قالب‌بندی یا نهایی‌سازی بومی. برای استفاده از متن محموله آماده‌شده در مشاهده نهایی، آن را حذف کنید. ارسال‌های صرفاً رسانه‌ای می‌توانند آن را حذف کنند.                             |
| `messageIds` / `receipt` | هویت‌های واقعی ارائه‌دهنده برای ارسال قابل‌مشاهده. یک `MessageReceipt` ترجیح داده می‌شود؛ هسته از شناسه اصلی ارائه‌دهنده آن برای `message_sent` استفاده می‌کند.                                                                                            |
| `visibleReplySent`       | فقط زمانی روی `false` تنظیم کنید که ارائه‌دهنده هیچ پیش‌نمایش یا پیام نهایی قابل‌مشاهده‌ای تولید نکرده باشد. هسته برای آن نتیجه، `message_sent` موفق منتشر نمی‌کند.                                                                          |
| `finalization`           | یک promise برای تسویه بومی با تأخیر همان محموله منطقی، مانند بستن یا ویرایش یک کارت جریانی درجا. فیلدهای حل‌شده آن پیش از مشاهده نهایی و `onDelivered`، نتیجه فوری را بازنویسی می‌کنند. |

گزینه `observeMessageSent` آداپتور تحویل را روی `true` تنظیم کنید، هنگامی که هسته
باید رویدادهای متعارف Plugin و داخلی `message_sent` را برای ارسال‌های
غیرپایدار این آداپتور منتشر کند. این گزینه را از `deliver` برنگردانید و
آن رویدادها را در Plugin نیز منتشر نکنید. ارسال‌های پایدار از قبل از طریق
مالک خروجی مشترک منتشر می‌شوند و تکرار نمی‌شوند.

به‌ازای هر محموله منطقی یک نتیجه برگردانید. `finalization` یک ارسال دوم نیست و
نباید `reply_payload_sending` یا `message_sending` را دوباره اجرا کند. به‌محض اینکه
`deliver` برمی‌گردد، هسته ردشدن promise نهایی‌سازی را مشاهده می‌کند تا
بدون رسیدگی نماند؛ هسته همچنان پس از تسویه توزیع پاسخ، منتظر promise اصلی
می‌ماند. سپس به‌ازای هر محموله حداکثر یک مشاهده نهایی با
محتوای نهایی‌شده و شناسه ارائه‌دهنده منتشر می‌کند. در صورت وجود `onDelivered`،
نتیجه تسویه‌شده پس از آن مشاهده به آن داده می‌شود.

هنگام شکست تحویل بومی، `deliver` یا `finalization` را رد کنید. اگر هیچ ارسال
ارائه‌دهنده‌ای تلاش نشد، `PlatformMessageNotDispatchedError` را از
`openclaw/plugin-sdk/error-runtime` پرتاب کنید؛ هسته یک رویداد نادرست `message_sent`
را سرکوب می‌کند. اگر یک ارسال بومی پیش از شکست یک عملیات بعدی قابل‌مشاهده شد،
زیرمجموعه قابل‌مشاهده را در خطا حفظ کنید:

```ts
import { createChannelPartialDeliveryError } from "openclaw/plugin-sdk/channel-inbound";

throw createChannelPartialDeliveryError(cause, {
  visibleReplySent: true,
  content: finalizedVisibleText,
  receipt,
});
```

هسته یک مشاهده نهایی ناموفق را با آن محتوا و هویت قابل‌مشاهده برای ارائه‌دهنده
منتشر می‌کند، سپس تحویل را ناموفق نگه می‌دارد تا فراخوان‌ها موفقیت جزئی را
با یک ارسال بی‌نقص اشتباه نگیرند. پس از قابل‌مشاهده‌شدن هرگونه
پیش‌نمایش، پیش‌نویس، پیوست یا پیام نهایی، `visibleReplySent: false` را گزارش نکنید.

هنگامی که `reply_payload_sending` یا `message_sending` ثبت شده است، آن قلاب‌ها
باید پیش از ایجاد هر چیز قابل‌مشاهده برای ارائه‌دهنده تسویه شوند، زیرا هر قلاب
می‌تواند محموله منطقی را بازنویسی یا لغو کند. یک پیش‌نمایش بومی زودهنگام،
محتوای پیش از بازنویسی را افشا می‌کند یا یک پیش‌نویس لغوشده باقی می‌گذارد.
محتوای پیش‌نمایش را تا زمانی که محموله پذیرفته‌شده به `deliver` می‌رسد، بافر کنید؛ توزیع‌کننده‌های سازگاری که
پیش‌نمایش‌ها را زودتر آغاز می‌کنند باید تا زمانی که یکی از این قلاب‌ها ثبت شده است،
آن پیش‌نمایش زودهنگام را سرکوب کنند. برای مسیرهای پیش‌نمایش جدید از کمک‌تابع‌های
پیش‌نمایش زنده قابل‌نهایی‌سازی در [API خروجی کانال](/fa/plugins/sdk-channel-outbound) استفاده کنید.

## مهاجرت

نام‌های مستعار زمان‌اجرای `runtime.channel.turn.*` حذف شدند. استفاده کنید از:

- `runtime.channel.inbound.run(...)` برای رویدادهای ورودی خام.
- `runtime.channel.inbound.dispatchReply(...)` برای زمینه‌های پاسخ سرهم‌شده.
- `runtime.channel.inbound.buildContext(...)` برای محموله‌های زمینه ورودی.
- `runtime.channel.inbound.runPreparedReply(...)`، منسوخ‌شده، فقط برای
  مسیرهای توزیع آماده‌شده تحت مالکیت کانال که از قبل بستار توزیع خود را
  سرهم می‌کنند.

کد Plugin جدید نباید APIهای کانال با نام `turn` معرفی کند. واژگان نوبت مدل یا
عامل را در کد عامل/ارائه‌دهنده نگه دارید؛ Pluginهای کانال از اصطلاحات ورودی،
پیام، تحویل و پاسخ استفاده می‌کنند.