> 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. # تنظیمات ربات > خواندن و تغییر تنظیمات ربات: بستن خودکار گفتگو، ارجاع به اپراتور، ساعت کاری، هوش مصنوعی و اپراتور هوش مصنوعی. هر ربات همان تنظیماتی را دارد که مشتری شما در پنل پارس‌چت می‌بیند: گفتگوی بی‌فعالیت کی بسته شود، وقتی یک نفر گفتگو را به دست می‌گیرد به مشتری چه گفته شود، ساعت کاری تیم، و هوش مصنوعی چطور پاسخ دهد. این تنظیمات را در هر پاسخی که ربات در آن هست می‌خوانید و هر کدام را با یک درخواست تغییر می‌دهید: ```bash curl -X PATCH "https://api-chat.parstechai.com/v1/robots/rbt_8fK2mQ" \ -H "Authorization: Bearer pk_live_xxxxxxxxxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{"settings": {"conversations": {"auto_close": {"idle_minutes": 720}}}}' ``` پاسخ، کل ربات است با همهٔ تنظیماتش به همان شکلی که اکنون هست. ## خواندن تنظیمات \[#reading-the-settings] `settings` در هر رباتی که دریافت می‌کنید هست: `GET /robots/{robot_id}`، هر مورد از `GET /robots`، و پاسخ‌های `POST /robots` و `PATCH /robots/{robot_id}`. **`Response`** ```json Response { "id": "rbt_8fK2mQ", "name": "Rose Flower Shop", "external_id": "shop_10422", "description": "Flower shop on Instagram", "is_active": true, "channels": [{ "id": "chn_3pQ7xL", "type": "instagram", "is_active": true }], "created_at": "2026-09-20T11:04:33Z", "settings": { "conversations": { "auto_close": { "enabled": true, "idle_minutes": 360, "max_idle_minutes": 21600 }, "operator_handover": { "message": "An operator will join you shortly.", "send_message": true }, "offline": { "message": "Our team is offline right now; we will reply when we are back.", "send_message": true }, "busy": { "message": "Our operators are busy; we will reply as soon as we can.", "send_message": false, "after_seconds": 300 }, "offline_message": "Our team is offline right now; we will reply when we are back.", "ai_failure_message": null, "working_hours": { "enabled": true, "time_zone": "Asia/Tehran", "days": { "SAT": [{ "start": "09:00", "end": "18:00" }], "SUN": [{ "start": "09:00", "end": "13:00" }, { "start": "16:00", "end": "20:00" }], "MON": [{ "start": "09:00", "end": "18:00" }], "TUE": [{ "start": "09:00", "end": "18:00" }], "WED": [{ "start": "09:00", "end": "18:00" }], "THU": [{ "start": "09:00", "end": "13:00" }], "FRI": [] } } }, "ai": { "enhanced_accuracy": false, "creativity": 50, "language": "auto", "topic": "Flower shop: roses and tulips, delivery inside Tehran only" }, "ai_operator": { "enabled": true, "display_name": "Rose assistant", "start_mode": "on_first_message", "availability": "always", "wait_minutes": 3 } } } ``` **رباتی که هیچ تنظیمی را تغییر نداده، مقداری را نشان می‌دهد که واقعاً اعمال می‌شود**، نه یک مقدار نمایشی. برای بستن خودکار گفتگو این همان قاعدهٔ امروز است: `{"enabled": true, "idle_minutes": 10080}`، یعنی یک هفته. **`settings.ai` و `settings.ai_operator` برای حسابی که بستهٔ پیام هوش مصنوعی ندارد `null` هستند.** این دو به بسته‌ای نیاز دارند که پیام هوش مصنوعی داشته باشد. بسته‌ای که پیام‌های این دوره‌اش تمام شده هم حساب می‌شود: تنظیمات با کم شدن موجودی قفل و باز نمی‌شوند. ## تغییر تنظیمات \[#changing-them] `PATCH /robots/{robot_id}` هر زیرمجموعه‌ای از این فیلدها را می‌پذیرد: * `name`، `external_id`، `description`، `is_active` * `settings.conversations`، `settings.ai`، `settings.ai_operator` همین شیء `settings` هنگام ساختن ربات با `POST /robots` هم پذیرفته می‌شود؛ هر چیزی را که نفرستید مقدار پیش‌فرض می‌گیرد. > **Note** > > **فقط چیزی که می‌فرستید تغییر می‌کند و شیءهای تودرتو با هم ادغام می‌شوند.** فرستادن > `{"settings": {"conversations": {"auto_close": {"idle_minutes": 720}}}}` مقدار `enabled` را همان‌طور > که بود نگه می‌دارد. شیء `days` در ساعت کاری فقط روزهایی را تغییر می‌دهد که نام می‌برد. چهار قاعده برای هر درخواست برقرار است: 1. **همه یا هیچ.** اگر بخشی از درخواست رد شود، هیچ چیز از آن ذخیره نمی‌شود، حتی بخش‌های درست. 2. **فیلد ناشناخته** با `422` رد می‌شود و هرگز نادیده گرفته نمی‌شود، تا فیلدی که اشتباه تایپ شده به‌جای ذخیره‌شده پذیرفته نشود. 3. **`null` فقط برای `external_id` و `description` پذیرفته می‌شود** و آن‌ها را پاک می‌کند. جای دیگر `422` است: برای نگه داشتن یک فیلد، آن را نفرستید. 4. **بدنهٔ خالی `{}`** چیزی را تغییر نمی‌دهد و ربات را برمی‌گرداند. این درخواست به مجوز `robot:create` روی کلید شما نیاز دارد، همان مجوزی که ربات می‌سازد و حذف می‌کند. ## گفتگوها \[#conversations] | فیلد | نوع | مقدارهای مجاز | پیش‌فرض | | -------------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- | | `auto_close.enabled` | boolean | | `true` | | `auto_close.idle_minutes` | integer | ۱۵ تا ۲۱۶۰۰ (۱۵ روز) | `10080` (۷ روز) | | `auto_close.max_idle_minutes` | integer | فقط‌خواندنی، همیشه ۲۱۶۰۰ | `21600` | | `operator_handover.message` | string | حداکثر ۵۰۰ کاراکتر؛ وقتی `send_message` روشن است الزامی است | متن فارسی پیش‌فرض پارس‌چت | | `operator_handover.send_message` | boolean | | `true` | | `offline.message` | string | حداکثر ۵۰۰ کاراکتر؛ وقتی `send_message` روشن است الزامی است | متن فارسی پیش‌فرض پارس‌چت | | `offline.send_message` | boolean | | `false` | | `busy.message` | string | حداکثر ۵۰۰ کاراکتر؛ وقتی `send_message` روشن است الزامی است | متن فارسی پیش‌فرض پارس‌چت | | `busy.send_message` | boolean | | `false` | | `busy.after_seconds` | integer | ۳۰ تا ۳۶۰۰ | `300` | | `offline_message` | string | **منسوخ**: همان متن `offline.message`؛ ۱ تا ۵۰۰ کاراکتر، فقط فاصله متن پیش‌فرض را برمی‌گرداند | | | `ai_failure_message` | string | **منسوخ و بی‌اثر**؛ در پاسخ همیشه `null` است | `null` | | `working_hours.enabled` | boolean | `false` یعنی همهٔ ساعت‌ها ساعت کاری‌اند | `false` | | `working_hours.time_zone` | string | یک منطقهٔ زمانی IANA، مثل `Asia/Tehran` | `UTC` | | `working_hours.days` | object | کلیدهای `SAT` `SUN` `MON` `TUE` `WED` `THU` `FRI`؛ هر کدام فهرستی از `{"start", "end"}` به شکل `HH:MM` که `start` پیش از `end` باشد؛ `[]` یعنی آن روز تعطیل است | همهٔ روزها `[]` | ### گفتگو کی بسته می‌شود \[#when-a-conversation-closes] گفتگویی که به اندازهٔ `idle_minutes` ربات پیامی نداشته باشد بسته می‌شود و رویداد `chat` با `status: "closed"` دریافت می‌کنید. بستن هر ساعت یک بار انجام می‌شود، پس یک گفتگو تا حدود یک ساعت پس از رسیدن به حدش بسته می‌شود. * **`enabled: false` به معنای «هرگز» نیست.** گفتگو باز هم پس از ۱۵ روز (۲۱۶۰۰ دقیقه) بدون پیام بسته می‌شود. `idle_minutes` نگه داشته می‌شود، پس با روشن کردن دوبارهٔ بستن خودکار همان مقدار برمی‌گردد. * **مشتری‌ای که دوباره پیام بدهد، همان گفتگو را باز می‌کند**: همان `conversation_id`، وضعیت `not_answered`، یک رویداد `chat` دیگر، و هوش مصنوعی با زمینهٔ تازه شروع می‌کند. * **این تنظیم همهٔ کانال‌هایی را که پارس‌چت برای ربات اداره می‌کند پوشش می‌دهد**: اینستاگرام، تلگرام، واتس‌اپ، گپ، ابزارک (ویجت) وب‌سایت و Direct API. گفتگوهای گفتینو و کریسپ از چرخهٔ عمر خود آن سرویس‌ها پیروی می‌کنند. ### آنچه به مشتریِ منتظرِ اپراتور گفته می‌شود \[#what-the-customer-is-told-while-waiting-for-a-person] هر ربات سه پیام دارد. هر کدام در هر گفتگو حداکثر یک بار فرستاده می‌شود. | پیام | کی فرستاده می‌شود | | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | `operator_handover` | هوش مصنوعی گفتگو را به یک نفر می‌سپارد: خودش اپراتور می‌خواهد، مشتری پاسخی را نمی‌پسندد، مشتری پیام صوتی می‌فرستد، یا هوش مصنوعی نمی‌تواند پاسخ دهد. | | `offline` | مشتری منتظر یک نفر است و ربات آفلاین است: بیرون از `working_hours`. | | `busy` | مشتری منتظر یک نفر است، ربات آنلاین است و تا `after_seconds` کسی پاسخ نداده است. | * **`operator_handover` در همهٔ کانال‌ها فرستاده می‌شود**، گفتینو و کریسپ هم. فقط وقتی فرستاده می‌شود که هوش مصنوعی در حال پاسخ دادن بوده است: گفتگویی که هوش مصنوعی به آن پاسخ نداده (مثلاً وقتی پیام‌های هوش مصنوعی شما تمام شده) «سپرده» نمی‌شود و پیام `operator_handover` نمی‌گیرد. * **`offline` و `busy` در اینستاگرام، تلگرام، واتس‌اپ، گپ و ابزارک وب‌سایت فرستاده می‌شوند.** گفتینو و کریسپ تنظیمات خودشان را برای این‌ها دارند، پس آن‌جا فرستاده نمی‌شوند. * **مشتریِ منتظر** کسی است که هوش مصنوعی به پیامش پاسخ نمی‌دهد: گفتگو با تیم شماست، هوش مصنوعی خاموش است، یا در این زمان پاسخ نمی‌دهد (`ai_operator.availability`). * **وقتی هوش مصنوعی پس از `wait_minutes` پاسخ می‌دهد** (`start_mode: "if_operator_not_respond"`)، پاسخ هوش مصنوعی جای `busy` را می‌گیرد. * پیامی که روشن است متن لازم دارد: `send_message: true` با `message` خالی با `422` رد می‌شود. ## هوش مصنوعی \[#ai] به بستهٔ پیام هوش مصنوعی نیاز دارد. | فیلد | نوع | مقدارهای مجاز | پیش‌فرض | | ------------------- | ------- | ----------------------------------------------------------------------------------- | ------- | | `enhanced_accuracy` | boolean | هر پاسخ را پیش از فرستادن بررسی می‌کند؛ برای هر پیام دو واحد هوش مصنوعی مصرف می‌کند | `false` | | `creativity` | integer | ۰ به محتوای مشتری شما نزدیک می‌ماند، ۱۰۰ آزادترین است | `50` | | `language` | string | `auto` (زبان خود مشتری)، `persian`، `english`، `dutch` | `auto` | | `topic` | string | اینکه ربات دربارهٔ چه پاسخ می‌دهد؛ همراه هر پرسش به هوش مصنوعی داده می‌شود | `""` | `topic` همان **معرفی بات** در پنل است. از پیام بعدی مشتری اعمال می‌شود: چیزی دوباره آموزش داده نمی‌شود و کاراکتری مصرف نمی‌شود. ۵ کاراکتر یا کمتر یعنی خالی. ## اپراتور هوش مصنوعی \[#ai-operator] به بستهٔ پیام هوش مصنوعی نیاز دارد. | فیلد | نوع | مقدارهای مجاز | پیش‌فرض | | -------------- | ------- | ------------------------------------------------------------------------------------------------- | ------------------ | | `enabled` | boolean | `false`: هوش مصنوعی هرگز پاسخ نمی‌دهد | `true` | | `display_name` | string | ۱ تا ۵۰ کاراکتر؛ نام هوش مصنوعی در فهرست اپراتورها | `ربات پشتیبانی` | | `start_mode` | string | `on_first_message`، یا `if_operator_not_respond` برای اینکه اول `wait_minutes` منتظر یک نفر بماند | `on_first_message` | | `availability` | string | `online`، `offline` یا `always`: هوش مصنوعی نسبت به آنلاین بودن تیم کی پاسخ دهد | `always` | | `wait_minutes` | integer | ۱ تا ۱۰۰۸۰ (یک هفته)؛ فقط در `if_operator_not_respond` به کار می‌رود | `3` | ## غیرفعال کردن ربات \[#deactivating-a-robot] `{"is_active": false}` همان کلید فعال‌سازی پنل است و **توقف موقت نیست**: * همهٔ کانال‌های ربات خاموش می‌شوند (`is_active: false` روی هر کانال) و ظرفیت کانالشان آزاد می‌شود. فقط کانال‌های فعال در بستهٔ شما حساب می‌شوند. * ربات جای خودش را در ظرفیت ربات‌ها نگه می‌دارد: ظرفیت ربات همهٔ ربات‌های موجود را می‌شمارد. برای آزاد کردن آن، ربات را حذف کنید. * `{"is_active": true}` ربات را دوباره فعال می‌کند اما **کانال‌هایش را خاموش نگه می‌دارد**. هر کانال را با `PATCH /robots/{robot_id}/channels/{channel_id}` دوباره روشن کنید که ظرفیت کانال را مثل همیشه بررسی می‌کند. برای اینکه فقط هوش مصنوعی پاسخ ندهد و کانال‌ها روشن بمانند، `settings.ai_operator.enabled` را `false` کنید. ## آنچه در این API نیست \[#not-in-this-api] * **دستورالعمل اختصاصی (پرامپت).** پرامپت ربات فقط از راه دستیار پرامپت پنل تغییر می‌کند: هوش مصنوعی درخواست را بازنویسی می‌کند، بخش‌هایی را که نپذیرفته گزارش می‌دهد و مشتری شما نتیجه را تأیید می‌کند. این فیلدی نیست که اینجا تنظیم شود: `settings.ai.instructions` به‌عنوان فیلد ناشناخته رد می‌شود. * **تصویر اپراتور هوش مصنوعی**، که بارگذاری فایل است. * **کنترل‌های بسته**، مثل محدودیت پیام. این‌ها را پارس‌چت تنظیم می‌کند. ## نمونه‌ها \[#examples] ### فقط تغییر بازهٔ بستن خودکار \[#change-only-the-auto-close-period] **`Request`** ```json Request { "settings": { "conversations": { "auto_close": { "idle_minutes": 720 } } } } ``` `200`، کل ربات، با `"auto_close": {"enabled": true, "idle_minutes": 720, "max_idle_minutes": 21600}`. ### خاموش کردن بستن خودکار \[#turn-auto-close-off] **`Request`** ```json Request { "settings": { "conversations": { "auto_close": { "enabled": false } } } } ``` `200`، با `"auto_close": {"enabled": false, "idle_minutes": 720, "max_idle_minutes": 21600}`. اکنون گفتگوها پس از ۱۵ روز بدون پیام بسته می‌شوند. ### چند تنظیم با هم \[#several-settings-at-once] **`Request`** ```json Request { "name": "Rose Flower Shop (Tehran)", "settings": { "conversations": { "operator_handover": { "send_message": true, "message": "Connecting you to a person." }, "working_hours": { "enabled": true, "time_zone": "Asia/Tehran", "days": { "FRI": [{ "start": "10:00", "end": "14:00" }] } } }, "ai_operator": { "start_mode": "if_operator_not_respond", "wait_minutes": 5, "availability": "offline" } } } ``` `200`. جمعه اکنون از ۱۰:۰۰ تا ۱۴:۰۰ باز است و شش روز دیگر تغییری نکرده‌اند. هوش مصنوعی فقط بیرون از ساعت کاری و پس از ۵ دقیقه بی‌پاسخ ماندن از سوی اپراتور پاسخ می‌دهد، و به مشتری‌ای که به یک نفر سپرده می‌شود «Connecting you to a person.» گفته می‌شود. ### به مشتریِ منتظر بگو تیم آفلاین یا مشغول است \[#tell-waiting-customers-when-the-team-is-offline-or-busy] **`Request`** ```json Request { "settings": { "conversations": { "offline": { "send_message": true, "message": "Our team is offline right now; we will reply when we are back." }, "busy": { "send_message": true, "after_seconds": 120 } } } } ``` `200`. مشتری‌ای که بیرون از ساعت کاری منتظر است پیام آفلاین را می‌گیرد؛ کسی که در ساعت کاری دو دقیقه بی‌پاسخ منتظر بماند، پیام مشغول را با متن پیش‌فرض پارس‌چت می‌گیرد. ### تغییر topic \[#change-the-topic] **`Request`** ```json Request { "settings": { "ai": { "topic": "Flower shop: roses, tulips and orchids, delivery across Iran" } } } ``` `200`، با `topic` تازه که از پیام بعدی مشتری اعمال می‌شود. `"topic": ""` آن را حذف می‌کند. ### پاک کردن شناسهٔ خودتان و توضیحات \[#clear-your-own-id-and-description] **`Request`** ```json Request { "external_id": null, "description": null } ``` `200`، با `"external_id": null` و `"description": null`. ### ساختن ربات با تنظیمات \[#create-a-robot-with-settings] ```bash curl -X POST "https://api-chat.parstechai.com/v1/robots" \ -H "Authorization: Bearer pk_live_xxxxxxxxxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{"name": "Orchid Lab", "external_id": "shop_20077", "settings": {"conversations": {"auto_close": {"enabled": true, "idle_minutes": 1440}}}}' ``` `201`، کل ربات، با مقدار پیش‌فرض برای هر تنظیمی که نفرستاده‌اید. ## وقتی تغییری رد می‌شود \[#when-a-change-is-refused] هیچ چیز از درخواستِ ردشده ذخیره نمی‌شود. | درخواست | پاسخ | | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | `{"settings": {"ai": {"creativity": 70}}}` روی حسابی بدون بستهٔ هوش مصنوعی | `403 ai_not_in_plan`: «Your plan does not include AI messages, so AI settings cannot be changed.» | | `{"settings": {"conversations": {"auto_close": {"idle_minutes": 30000}}}}` | `422 validation_failed`: ``"`settings.conversations.auto_close.idle_minutes`: Input should be less than or equal to 21600"`` | | `{"settings": {"conversations": {"auto_close": {"idle_minute": 720}}}}` (اشتباه تایپی) | `422 validation_failed`: ``"`settings.conversations.auto_close.idle_minute`: Extra inputs are not permitted"`` | | `{"settings": {"conversations": {"offline": {"send_message": true, "message": " "}}}}` | `422 validation_failed`: «A message that is switched on needs a text.»، با `details.field` برابر `settings.conversations.offline.message` | | `{"settings": {"conversations": {"ai_failure_message": "shout"}}}` | `422 validation_failed`: ``"`settings.conversations.ai_failure_message`: Input should be 'offline_message', 'handover_message' or 'none'"`` | | `{"settings": {"ai": {"creativity": null}}}` | `422 validation_failed`: ``"`settings.ai.creativity`: Input should be a valid integer"`` | | `{"settings": {"ai": {"instructions": "…"}}}` | `422 validation_failed`: دستورالعمل اختصاصی بخشی از این API نیست | | `{"external_id": "shop_20077"}` وقتی ربات دیگری از شما آن را دارد | `409 conflict` | | شناسهٔ رباتی که مال شما نیست یا وجود ندارد | `404 not_found`، پاسخ هر دو یکی است | همین `422` برای `creativity: 150`، `wait_minutes: 0`، `"start": "25:00"`، بازه‌ای که `start` آن پیش از `end` نباشد، منطقهٔ زمانی ناشناخته، `language: "french"` و `display_name: ""` هم برمی‌گردد. پیام، فیلد را با مسیرش نام می‌برد؛ بر اساس `error.code` تصمیم بگیرید، نه متن پیام که ممکن است تغییر کند.