پاسخ به مشتریان

اپراتورهای شما از پنل شما به مشتریان نهایی پاسخ می‌دهند، نه از پنل ما. یک گفتگو به وب‌هوک شما می‌رسد، کارشناس شما پاسخی می‌نویسد و شما آن را از طریق این API برمی‌گردانید. پیام از همان کانالی که گفتگو به آن تعلق دارد به مشتری می‌رسد؛ پس یک فراخوانی واحد هم اینستاگرام را پوشش می‌دهد و هم تلگرام را.

ارسال پاسخ متنی

هر رویداد یک conversation_id دارد. برای پاسخ‌دادن همین کافی است.

curl -X POST https://api-chat.parstechai.com/v1/conversations/cnv_4dR8nW/messages \
  -H "Authorization: Bearer pk_live_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Yes, we deliver on Fridays. Shall I reserve one for you?",
    "external_id": "op_reply_5521"
  }'

{
  "conversation_id": "cnv_4dR8nW",
  "message_id": "msg_9wY7zA",
  "external_id": "op_reply_5521",
  "role": "operator",
  "type": "text",
  "text": "Yes, we deliver on Fridays. Shall I reserve one for you?",
  "attachments": [],
  "status": "sent",
  "created_at": "2026-09-20T11:33:05Z"
}

status با مقدار queued یعنی کانال به محدودیت نرخ درخواست خورده است و پیام را وقتی ظرفیت آزاد شد تحویل می‌دهیم. چیزی دور ریخته نمی‌شود.

ارسال فایل یا پیام صوتی

دو مرحله دارد: فایل را بارگذاری کنید، سپس پیامی بفرستید که به آن ارجاع می‌دهد.

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

۱. بارگذاری

curl -X POST https://api-chat.parstechai.com/v1/attachments \
  -H "Authorization: Bearer pk_live_xxxxxxxxxxxxxxxxxxxx" \
  -F "conversation_id=cnv_4dR8nW" \
  -F "file=@product-photo.jpg"

{
  "id": "att_5kR2nP",
  "identifier": "9f2c41b8e7d4",
  "name": "product-photo.jpg",
  "url": "https://cdn.parstechai.com/a/9f2c41b8e7d4.jpg",
  "type": "image"
}

۲. ارسال

curl -X POST https://api-chat.parstechai.com/v1/conversations/cnv_4dR8nW/messages \
  -H "Authorization: Bearer pk_live_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "attachment_ids": ["att_5kR2nP"], "external_id": "op_photo_77" }'

{
  "conversation_id": "cnv_4dR8nW",
  "message_id": "msg_1xZ8bC",
  "external_id": "op_photo_77",
  "role": "operator",
  "type": "image",
  "text": "",
  "attachments": [],
  "status": "sent",
  "created_at": "2026-09-20T11:35:41Z"
}

اندازه فایل یکی از ابعاد بسته است و هنگام بارگذاری برای هر فایل جداگانه بررسی می‌شود:

نگارش‌های جایگزین رایج هم پذیرفته می‌شوند (image/jpg، video/avi، audio/m4a، audio/wave، audio/x-wav، audio/vnd.wave). این دقیقاً همان چیزی است که اینستاگرام تحویل می‌دهد: GIF، WebP و فرمت‌های دیگر هنگام بارگذاری رد می‌شوند، نه اینکه پذیرفته شوند و بعد هنگام ارسال شکست بخورند.

هر بسته‌ای که دسترسی API دارد هر چهار نوع را ارسال می‌کند؛ تفاوت سطح‌ها در اندازه است، نه در اینکه چه نوع فایلی را می‌توانید بفرستید. اگر قرارداد شما سقف‌های دیگری تعیین کرده باشد، همان‌ها اعمال می‌شوند.

نوع فایلی خارج از این فهرست، یا فایلی بزرگ‌تر از سقف بسته شما، پیش از ذخیره با 422 validation_failed رد می‌شود؛ برای سقف اندازه، details شامل kind، cap_mb و size_bytes است. نوعی از فایل که بسته شما شامل آن نیست، خطای 403 attachment_not_in_plan می‌دهد. بارگذاری‌های ارسال‌نشده پس از ۲۴ ساعت دور ریخته می‌شوند.

محدودیت‌های کامل و ارتباط آن‌ها با محدودیت‌های خود اینستاگرام در محدودیت نرخ درخواست آمده است.

نمایش نشانگر «در حال نوشتن»

وقتی کارشناس شما شروع به نوشتن می‌کند این را فراخوانی کنید تا مشتری همان نشانه‌ای را ببیند که در هر برنامه گفتگوی دیگری می‌بیند.

curl -X POST https://api-chat.parstechai.com/v1/conversations/cnv_4dR8nW/typing \
  -H "Authorization: Bearer pk_live_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "is_typing": true }'

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

ساختن صف اپراتور

گفتگوها را بر اساس وضعیت فیلتر کنید تا آن‌هایی را که منتظر یک انسان‌اند پیدا کنید.

curl "https://api-chat.parstechai.com/v1/conversations?status=operator_attention" \
  -H "Authorization: Bearer pk_live_xxxxxxxxxxxxxxxxxxxx"

{
  "data": [
    {
      "id": "cnv_4dR8nW",
      "robot_id": "rbt_8fK2mQ",
      "channel_id": "chn_3pQ7xL",
      "status": "operator_attention",
      "client": { "id": "iguser_88213", "username": "sara.k" },
      "last_message_at": "2026-09-20T11:20:44Z",
      "unread_count": 2,
      "created_at": "2026-09-20T11:08:59Z"
    }
  ],
  "pagination": { "limit": 50, "offset": 0, "total_count": 1, "has_more": false }
}

unread_count تعداد پیام‌های مشتری از آخرین پاسخ یک اپراتور، هوش مصنوعی یا یک کارشناس است؛ یعنی آنچه هنوز منتظر پاسخ است.

لازم نیست این را مدام بپرسید (poll کنید). رویداد وب‌هوک chat همان لحظه‌ای که گفتگو وارد operator_attention می‌شود ارسال می‌شود؛ پس از رویداد برای به‌روزکردن صف و از این اندپوینت برای بازسازی آن پس از راه‌اندازی دوباره استفاده کنید.

بستن گفتگو

curl -X POST https://api-chat.parstechai.com/v1/conversations/cnv_4dR8nW/close \
  -H "Authorization: Bearer pk_live_xxxxxxxxxxxxxxxxxxxx"