تنظیمات ربات

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

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}}}}'

پاسخ، کل ربات است با همهٔ تنظیماتش به همان شکلی که اکنون هست.

خواندن تنظیمات

settings در هر رباتی که دریافت می‌کنید هست: GET /robots/{robot_id}، هر مورد از GET /robots، و پاسخ‌های POST /robots و PATCH /robots/{robot_id}.

{
  "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 هستند. این دو به بسته‌ای نیاز دارند که پیام هوش مصنوعی داشته باشد. بسته‌ای که پیام‌های این دوره‌اش تمام شده هم حساب می‌شود: تنظیمات با کم شدن موجودی قفل و باز نمی‌شوند.

تغییر تنظیمات

PATCH /robots/{robot_id} هر زیرمجموعه‌ای از این فیلدها را می‌پذیرد:

• name، external_id، description، is_active
• settings.conversations، settings.ai، settings.ai_operator

همین شیء settings هنگام ساختن ربات با POST /robots هم پذیرفته می‌شود؛ هر چیزی را که نفرستید مقدار پیش‌فرض می‌گیرد.

چهار قاعده برای هر درخواست برقرار است:

1. همه یا هیچ. اگر بخشی از درخواست رد شود، هیچ چیز از آن ذخیره نمی‌شود، حتی بخش‌های درست.
2. فیلد ناشناخته با 422 رد می‌شود و هرگز نادیده گرفته نمی‌شود، تا فیلدی که اشتباه تایپ شده به‌جای ذخیره‌شده پذیرفته نشود.
3. null فقط برای external_id و description پذیرفته می‌شود و آن‌ها را پاک می‌کند. جای دیگر 422 است: برای نگه داشتن یک فیلد، آن را نفرستید.
4. بدنهٔ خالی {} چیزی را تغییر نمی‌دهد و ربات را برمی‌گرداند.

این درخواست به مجوز robot:create روی کلید شما نیاز دارد، همان مجوزی که ربات می‌سازد و حذف می‌کند.

گفتگوها

گفتگو کی بسته می‌شود

گفتگویی که به اندازهٔ idle_minutes ربات پیامی نداشته باشد بسته می‌شود و رویداد chat با status: "closed" دریافت می‌کنید. بستن هر ساعت یک بار انجام می‌شود، پس یک گفتگو تا حدود یک ساعت پس از رسیدن به حدش بسته می‌شود.

• enabled: false به معنای «هرگز» نیست. گفتگو باز هم پس از ۱۵ روز (۲۱۶۰۰ دقیقه) بدون پیام بسته می‌شود. idle_minutes نگه داشته می‌شود، پس با روشن کردن دوبارهٔ بستن خودکار همان مقدار برمی‌گردد.
• مشتری‌ای که دوباره پیام بدهد، همان گفتگو را باز می‌کند: همان conversation_id، وضعیت not_answered، یک رویداد chat دیگر، و هوش مصنوعی با زمینهٔ تازه شروع می‌کند.
• این تنظیم همهٔ کانال‌هایی را که پارس‌چت برای ربات اداره می‌کند پوشش می‌دهد: اینستاگرام، تلگرام، واتس‌اپ، گپ، ابزارک (ویجت) وب‌سایت و Direct API. گفتگوهای گفتینو و کریسپ از چرخهٔ عمر خود آن سرویس‌ها پیروی می‌کنند.

آنچه به مشتریِ منتظرِ اپراتور گفته می‌شود

هر ربات سه پیام دارد. هر کدام در هر گفتگو حداکثر یک بار فرستاده می‌شود.

• operator_handover در همهٔ کانال‌ها فرستاده می‌شود، گفتینو و کریسپ هم. فقط وقتی فرستاده می‌شود که هوش مصنوعی در حال پاسخ دادن بوده است: گفتگویی که هوش مصنوعی به آن پاسخ نداده (مثلاً وقتی پیام‌های هوش مصنوعی شما تمام شده) «سپرده» نمی‌شود و پیام operator_handover نمی‌گیرد.
• offline و busy در اینستاگرام، تلگرام، واتس‌اپ، گپ و ابزارک وب‌سایت فرستاده می‌شوند. گفتینو و کریسپ تنظیمات خودشان را برای این‌ها دارند، پس آن‌جا فرستاده نمی‌شوند.
• مشتریِ منتظر کسی است که هوش مصنوعی به پیامش پاسخ نمی‌دهد: گفتگو با تیم شماست، هوش مصنوعی خاموش است، یا در این زمان پاسخ نمی‌دهد (ai_operator.availability).
• وقتی هوش مصنوعی پس از wait_minutes پاسخ می‌دهد (start_mode: "if_operator_not_respond")، پاسخ هوش مصنوعی جای busy را می‌گیرد.
• پیامی که روشن است متن لازم دارد: send_message: true با message خالی با 422 رد می‌شود.

هوش مصنوعی

به بستهٔ پیام هوش مصنوعی نیاز دارد.

topic همان معرفی بات در پنل است. از پیام بعدی مشتری اعمال می‌شود: چیزی دوباره آموزش داده نمی‌شود و کاراکتری مصرف نمی‌شود. ۵ کاراکتر یا کمتر یعنی خالی.

اپراتور هوش مصنوعی

به بستهٔ پیام هوش مصنوعی نیاز دارد.

غیرفعال کردن ربات

{"is_active": false} همان کلید فعال‌سازی پنل است و توقف موقت نیست:

• همهٔ کانال‌های ربات خاموش می‌شوند (is_active: false روی هر کانال) و ظرفیت کانالشان آزاد می‌شود. فقط کانال‌های فعال در بستهٔ شما حساب می‌شوند.
• ربات جای خودش را در ظرفیت ربات‌ها نگه می‌دارد: ظرفیت ربات همهٔ ربات‌های موجود را می‌شمارد. برای آزاد کردن آن، ربات را حذف کنید.
• {"is_active": true} ربات را دوباره فعال می‌کند اما کانال‌هایش را خاموش نگه می‌دارد. هر کانال را با PATCH /robots/{robot_id}/channels/{channel_id} دوباره روشن کنید که ظرفیت کانال را مثل همیشه بررسی می‌کند.

برای اینکه فقط هوش مصنوعی پاسخ ندهد و کانال‌ها روشن بمانند، settings.ai_operator.enabled را false کنید.

آنچه در این API نیست

• دستورالعمل اختصاصی (پرامپت). پرامپت ربات فقط از راه دستیار پرامپت پنل تغییر می‌کند: هوش مصنوعی درخواست را بازنویسی می‌کند، بخش‌هایی را که نپذیرفته گزارش می‌دهد و مشتری شما نتیجه را تأیید می‌کند. این فیلدی نیست که اینجا تنظیم شود: settings.ai.instructions به‌عنوان فیلد ناشناخته رد می‌شود.
• تصویر اپراتور هوش مصنوعی، که بارگذاری فایل است.
• کنترل‌های بسته، مثل محدودیت پیام. این‌ها را پارس‌چت تنظیم می‌کند.

نمونه‌ها

فقط تغییر بازهٔ بستن خودکار

{ "settings": { "conversations": { "auto_close": { "idle_minutes": 720 } } } }

200، کل ربات، با "auto_close": {"enabled": true, "idle_minutes": 720, "max_idle_minutes": 21600}.

خاموش کردن بستن خودکار

{ "settings": { "conversations": { "auto_close": { "enabled": false } } } }

200، با "auto_close": {"enabled": false, "idle_minutes": 720, "max_idle_minutes": 21600}. اکنون گفتگوها پس از ۱۵ روز بدون پیام بسته می‌شوند.

چند تنظیم با هم

{
  "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.» گفته می‌شود.

به مشتریِ منتظر بگو تیم آفلاین یا مشغول است

{
  "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

{ "settings": { "ai": { "topic": "Flower shop: roses, tulips and orchids, delivery across Iran" } } }

200، با topic تازه که از پیام بعدی مشتری اعمال می‌شود. "topic": "" آن را حذف می‌کند.

پاک کردن شناسهٔ خودتان و توضیحات

{ "external_id": null, "description": null }

200، با "external_id": null و "description": null.

ساختن ربات با تنظیمات

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، کل ربات، با مقدار پیش‌فرض برای هر تنظیمی که نفرستاده‌اید.

وقتی تغییری رد می‌شود

هیچ چیز از درخواستِ ردشده ذخیره نمی‌شود.

همین 422 برای creativity: 150، wait_minutes: 0، "start": "25:00"، بازه‌ای که start آن پیش از end نباشد، منطقهٔ زمانی ناشناخته، language: "french" و display_name: "" هم برمی‌گردد. پیام، فیلد را با مسیرش نام می‌برد؛ بر اساس error.code تصمیم بگیرید، نه متن پیام که ممکن است تغییر کند.