> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs-parschat.parstechai.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs-parschat.parstechai.com/_mcp/server.

# مفاهیم اصلی

> ربات‌ها، کانال‌ها و گفتگوها، و تنها قانونی که شکل هر یکپارچه‌سازی را تعیین می‌کند.

> **Warning**
>
> **نسخه پیش‌انتشار `v1`، منتشرشده در ۲۰۲۶-۰۹-۱۴.** این صفحه به شکل API متعهد است، نه به تاریخ
> آن. دقیقاً همان چیزی را می‌سازیم که اینجا مستند شده است. شکل API تا
> **۲۰۲۶-۱۰-۱۴** هنوز ممکن است تغییر کند؛ پس از آن، تغییرات از [نسخه‌بندی و پایداری](/documentation/reference/versioning-stability) پیروی می‌کنند.
>
> این بنر صفحه‌به‌صفحه و هم‌زمان با فعال‌شدن هر مسیر برداشته می‌شود. تا وقتی بنر هست، بر اساس
> قرارداد پیاده‌سازی کنید و فرض کنید آن مسیر هنوز قابل فراخوانی نیست.

## تنها قانون

**کانال همیشه متعلق به یک ربات است.** اتصال اینستاگرامِ مستقل وجود ندارد. اول ربات را بسازید،
سپس کانال را به آن متصل کنید.

```
create robot  →  attach channel  →  receive events
```

این قاعده در مدل داده اعمال می‌شود؛ قراردادی نیست که بتوانیم آن را سهل بگیریم. کانال بدون رباتی که
مالکش باشد نمی‌تواند وجود داشته باشد.

> **Warning**
>
> اتصال کانال پیش از ساخت ربات در اعتبارسنجی رد می‌شود. این رایج‌ترین خطا در اولین یکپارچه‌سازی است.

## اشیا

#### ربات

فضای کاری‌ای که گفتگوها، قانون‌های خودکارسازی و داده‌های آموزشی را نگه می‌دارد. `rbt_…`

#### کانال

یک بستر متصل، مثل یک صفحه اینستاگرام. دقیقاً متعلق به یک ربات است. `chn_…`

#### گفتگو

یک رشته گفتگو با یک کاربر نهایی، روی یک کانال. `cnv_…`

**هر ربات از هر نوع کانال حداکثر یکی دارد.** یک ربات نمی‌تواند دو صفحه اینستاگرام داشته باشد. برای
صفحه دوم یک ربات جداگانه بسازید.

## مشتری و کاربر نهایی دو شخص متفاوت‌اند

این دو واژه در سراسر این مستندات به کار می‌روند و هرگز به یک معنا نیستند.

|                 | چه کسی است                         | چه می‌کند                                                             |
| --------------- | ---------------------------------- | --------------------------------------------------------------------- |
| **مشتری**       | کسب‌وکاری که به آن خدمت می‌دهید    | یک ربات دارد. اپراتورهایش به گفتگوها پاسخ می‌دهند                     |
| **کاربر نهایی** | شخصی که به آن کسب‌وکار پیام می‌دهد | دایرکت اینستاگرام یا پیام تلگرامی را می‌فرستد که گفتگو را آغاز می‌کند |

اگر شریک تجاری ما هستید، مشتریان شما کسب‌وکارهای روی پلتفرم شما هستند و کاربران نهایی آن‌ها عموم
مردم‌اند. گفتگو همیشه میان یک **کاربر نهایی** و اپراتورها یا هوش مصنوعی یک **مشتری** است.

## یک ربات برای هر مشتری

اگر به مشتریان زیادی خدمت می‌دهید، برای هر مشتری یک ربات بسازید. همین کار است که گفتگوها،
قانون‌های خودکارسازی و داده‌های آموزشی یک مشتری را از مشتری دیگر جدا نگه می‌دارد.

کاربران نهایی به چنین تفکیکی نیاز ندارند: آن‌ها درون گفتگوهای یک ربات شناسایی می‌شوند، و اگر یک
شخص به دو مشتری مختلف پیام دهد، دو گفتگوی بی‌ارتباط ایجاد می‌شود.

## `external_id` شناسه خود شماست

هر ربات می‌تواند یک `external_id` داشته باشد: شناسه مشتری در سیستم خود شما. ما آن را در هر رویداد
برمی‌گردانیم، پس هیچ‌وقت به جدول تطبیق میان شناسه‌های ما و شما نیاز ندارید.

```json
{ "name": "Rose Flower Shop", "external_id": "shop_10422" }
```

`external_id` برای هر شریک یکتاست، پس شناسه‌های شما با شناسه‌های شریک دیگر تداخل ندارد. استفاده
دوباره از یکی از شناسه‌های خودتان `409` برمی‌گرداند.

> **Info**
>
> پیام‌ها هم `external_id` دارند، اما با کاربردی دیگر: کلید idempotency شماست. اگر پیامی با
> `external_id` تکراری بفرستید، پیام تکراری ساخته نمی‌شود.
> [رویدادهای وب‌هوک](/documentation/guides/webhook-events) را ببینید.

## ظرفیت

تعداد ربات‌ها و کانال‌هایی که می‌توانید داشته باشید از بسته‌تان می‌آید. اگر بیشتر نیاز دارید، با تیم
فروش ما تماس بگیرید.

وقتی ظرفیت تمام شود، `403 capacity_exhausted` دریافت می‌کنید. `details` وضعیت شما را نشان می‌دهد: `occupied` تعداد کانال‌های فعال شماست، `requested` تعدادی است که این فراخوانی نیاز دارد، و `capacity` سقفی است که بسته‌تان اجازه می‌دهد.

```json
{
  "error": {
    "code": "capacity_exhausted",
    "message": "You have reached the maximum number of channels your plan allows.",
    "request_id": "req_8f2Kq9mR",
    "details": { "occupied": 10, "requested": 1, "capacity": 10 }
  }
}
```

حذف ربات یا کانال ظرفیت را بلافاصله آزاد می‌کند. **غیرفعال‌کردن کانال هم ظرفیت را آزاد می‌کند** —
ظرفیت فقط کانال‌های فعال را می‌شمارد، پس صفحه مشتری‌ای که موقتاً متوقف شده، سابقه، قانون‌ها و
تنظیماتش را حفظ می‌کند بی‌آنکه جایی از ظرفیت را اشغال کند. [فعال و غیرفعال‌کردن کانال](/documentation/guides/when-a-plan-lapses#reactivating-after-a-renewal) را ببینید.