رفتن به محتوا
Mahvash/مستندات API
English

راهنماها

چت تعاملی پشتیبانی

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

بخش‌های این سناریو چطور به هم وصل‌اند

  1. 01پیام کاربر در چت
  2. 02بک‌اند شما
  3. 03stream از Responses
  4. 04نمایش زنده در چت

یک مثال واقعی

سفرنامه را در نظر بگیرید؛ یک آژانس مسافرتی با چت روی سایت. مسافران شبانه‌روز دربارهٔ رزروشان می‌پرسند: آیا می‌شود تاریخ را عوض کرد، چه باری شامل بلیت است، چه مدارکی لازم است. پاسخ بسیاری از این پرسش‌ها در تأییدیهٔ رزروی است که مسافر از قبل دارد.

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

آنچه کسب‌وکار به دست می‌آورد

  • پاسخ فوری و طبیعی که همزمان با نوشته‌شدن ظاهر می‌شود، مثل گفت‌وگو با یک انسان.
  • ادامهٔ زمینهٔ گفت‌وگو. پرسش‌های بعدی بدون تکرار حرف‌های مسافر کار می‌کنند.
  • صداقت در محدودیت‌ها. وقتی پاسخ در رزرو یا پایگاه دانش نیست، دستیار می‌تواند همین را بگوید و گفت‌وگو را به کارشناس بسپارد.
  • نشست پایدار. اتصال قطع‌شده از روی response ذخیره‌شده بازیابی می‌شود، نه اینکه دو بار هزینه شود.

با یک گفت‌وگوی واقعی ببینید

نوبتمسافردستیارآنچه بک‌اند ذخیره می‌کند
۱booking-confirmation.pdf را پیوست می‌کند: «می‌توانم پرواز کیشم را از ۱۲ام به ۱۴ام منتقل کنم؟»به‌صورت stream: «بلیت شما از نوع اکونومی انعطاف‌پذیر است؛ یک بار می‌توانید تاریخ را تغییر دهید و فقط مابه‌التفاوت نرخ را می‌پردازید…»UUID مربوط به asset و response resp_A
۲«تقریباً چقدر هزینه دارد؟»«تأییدیهٔ شما قیمت‌های فعلی را ندارد، پس نمی‌توانم مبلغ دقیق بگویم. می‌توانم شما را به کارشناس وصل کنم تا ظرفیت را بررسی کند.»response resp_B در ادامهٔ resp_A
۳دربارهٔ بار می‌پرسد؛ وسط پاسخ آنتن گوشی قطع می‌شود.پس از اتصال دوباره، پاسخ کامل از response ذخیره‌شده نمایش داده می‌شود.response resp_C که با شناسه بازیابی شده — بدون هزینهٔ دوباره

آنچه بک‌اند سفرنامه در هر نوبت می‌فرستد:

{
  "model": "auto",
  "stream": true,
  "input": "می‌توانم پرواز کیشم را از ۱۲ام به ۱۴ام منتقل کنم؟",
  "asset_ids": ["<booking-confirmation-asset-uuid>"]
}

// Your backend saves the id from response.created: resp_A

مرورگر هرگز مستقیم با مهوش صحبت نمی‌کند. با endpoint چت خود سفرنامه صحبت می‌کند که API key پروژه را نگه می‌دارد، متن را به‌صورت stream عبور می‌دهد و شناسهٔ هر response را کنار گفت‌وگو ذخیره می‌کند.

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

مرجع اصلی گفت‌وگو، چت شماست

کاربران، دسترسی‌های گفت‌وگو و ظاهر پیام‌ها در اپلیکیشن شما مدیریت می‌شوند. بک‌اند شما با API key پروژه یک stream از Responses مهوش باز می‌کند و فقط رویدادهای امن یا متن آماده‌شده را به مرورگر می‌فرستد.

آماده کردن زمینهٔ گفت‌وگو

  • یک پروژه و مدلی را انتخاب کنید که stream را پشتیبانی می‌کند.
  • وقتی کاربران در چند نوبت به یک فایل اشاره می‌کنند، آن را یک بار به‌عنوان asset پروژه آپلود کنید و UUID آن را در رکورد گفت‌وگو نگه دارید.
  • اگر چت باید از پایگاه دانش شما پاسخ دهد، ابزار file_search را برای یک vector store آماده اضافه کنید.

APIهای این مرحله

POST آپلود یک فایل قابل استفادهٔ مجدد (asset) ↗

stream یک نوبت و ادامهٔ گفت‌وگو

  1. ۱یک request به Responses با stream: true، پیام کاربر و asset_ids لازم بسازید.
  2. ۲شناسهٔ response را بلافاصله از رویداد response.created ذخیره کنید.
  3. ۳هر response.output_text.delta را به محض رسیدن به پیام اضافه کنید.
  4. ۴با رسیدن response.completed، متن نهایی و میزان مصرف را ذخیره کنید.
  5. ۵در نوبت بعد، شناسهٔ response قبلی را در previous_response_id بفرستید تا مدل ادامهٔ گفت‌وگو را بداند.

response.incomplete و response.failed را صریحاً مدیریت کنید؛ این‌ها هم نتیجه‌های عادی‌اند، نه خطاهای غیرمنتظره.

APIهای این مرحله

POST ساخت response ↗GET دریافت response ↗

نمونهٔ سرور با stream

نمونه‌های TypeScript و Python رویدادهای SSE را می‌خوانند و شناسهٔ response نهایی را ثبت می‌کنند. در production رویدادها را از طریق بک‌اند احرازشدهٔ خودتان به مرورگر برسانید و هیچ‌وقت قطع شدن اتصال را نشانهٔ شکست ندانید.

نمونهٔ پیاده‌سازی

// Server route called by your authenticated chat UI.
const response = await fetch("https://api.mahvashai.ir/v1/responses", {
  method: "POST",
  headers: { Authorization: "Bearer " + process.env.MAHVASH_PROJECT_KEY!, "Content-Type": "application/json" },
  body: JSON.stringify({ model: "auto", input: userMessage, stream: true,
    previous_response_id: chat.lastCompletedResponseId || undefined,
    asset_ids: chat.assetIds })
});
if (!response.ok || !response.body) throw new Error("Stream could not start");
// Parse the SSE data frames on your server and forward only the events your UI needs.
for await (const event of parseSse(response.body)) {
  if (event.type === "response.output_text.delta") await ui.sendDelta(event.delta);
  if (event.type === "response.completed") {
    await db.chats.saveCompletedResponse(chat.id, event.response.id);
  }
  if (event.type === "response.failed" || event.type === "response.incomplete") {
    await ui.showRecoveryState();
  }
}

نمونهٔ خروجی این مرحله

data: {"type":"response.created","sequence_number":1,"response":{"id":"resp_example","status":"in_progress"}}

data: {"type":"response.output_text.delta","sequence_number":4,"output_index":0,"content_index":0,"delta":"I can help"}

data: {"type":"response.completed","sequence_number":9,"response":{"id":"resp_example","status":"completed"}}

data: [DONE]

این فقط بخشی از response به‌عنوان نمونه است. روند کار و داده‌های مشتری در اپلیکیشن خود شما مدیریت می‌شوند.

وضعیت‌های رابط گفت‌وگو

در رابط کاربری سه وضعیت را در نظر بگیرید: در حال نوشتن وقتی تکه‌های متن می‌رسند، کامل بعد از رویداد پایانی، و قابل بازیابی وقتی اتصال پیش از پایان قطع می‌شود. شناسهٔ response و assetها را کنار گفت‌وگوی درست و متعلق به همان مشتری نگه دارید.

تکرار امن

اگر اتصال پس از فرستادن request قطع شد، پیش از هر کاری response ذخیره‌شده را با شناسه‌اش بازیابی کنید؛ request تازه یک اجرای پولی دیگر است. گزینهٔ «تلاش دوباره» را فقط وقتی به کاربر نشان دهید که response ذخیره‌شده نشان دهد آن نوبت واقعاً ناموفق بوده است.

previous_response_id گفت‌وگو را فقط در پروژه‌ای ادامه می‌دهد که صاحب آن است؛ هرگز سعی نکنید responseی از پروژهٔ دیگر را ادامه دهید.

همین الگو برای کسب‌وکارهای دیگر

  • فروشگاه‌های اینترنتی — دستیار خرید که از اطلاعات محصول و سفارش پاسخ می‌دهد.
  • اپ‌های بانکی و فین‌تک — راهنمای درون‌برنامه‌ای بر اساس شرایط منتشرشده.
  • دانشگاه‌ها — چت پذیرش و خدمات دانشجویی بر اساس مقررات رسمی.
  • محصولات نرم‌افزاری — راهنمای درون‌برنامه‌ای که می‌تواند screenshot یا فایل پیوست کاربر را بخواند.
← همهٔ سناریوهای پیاده‌سازی