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

راهنماها

میز پشتیبانی صوتی

تماس ضبط‌شدهٔ پشتیبانی را به متن، پیش‌نویس پاسخِ متکی بر دانش سازمان و در صورت نیاز فایل صوتی تبدیل کنید؛ درحالی‌که تصمیم دربارهٔ آنچه برای مشتری فرستاده می‌شود با کارشناس است.

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

  1. 01فایل ضبط تماس
  2. 02بک‌اند پشتیبانی
  3. 03تبدیل به متن ← پاسخ ← تبدیل به گفتار
  4. 04صفحهٔ کار کارشناس

یک مثال واقعی

سپهرنت را در نظر بگیرید؛ یک ارائه‌دهندهٔ اینترنت با مرکز تماس شلوغ. پس از هر تماس، کارشناس باید خلاصه‌ای بنویسد، قدم بعدی را مشخص کند و اغلب پیام پیگیری برای مشتری بفرستد. این یادداشت‌برداری زمان می‌برد و کیفیتش از کارشناسی به کارشناس دیگر فرق می‌کند.

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

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

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

با یک تماس واقعی ببینید

مرحلهچه اتفاقی می‌افتددر این مثال
۱. ضبط تماسسیستم تلفن فایل ضبط‌شده را ذخیره و یک تیکت ایجاد می‌کند.تماسی سه‌دقیقه‌ای دربارهٔ کندی اینترنت، call-58213.m4a.
۲. متن تماسمهوش صوت را به متن تبدیل می‌کند.«این هفته هر شب اینترنتم خیلی کند است، مخصوصاً بعد از ساعت هشت…»
۳. پیش‌نویس پیگیریپاسخی بر اساس راهنمای عیب‌یابی نوشته می‌شود.«کندی اینترنت در ساعات شب اغلب به شلوغی Wi-Fi برمی‌گردد. لطفاً یک شب با کابل وصل شوید…»
۴. تأیید کارشناسکارشناس پیشنهاد تست خط را اضافه و تأیید می‌کند.متن تأییدشده روی تیکت ذخیره می‌شود.
۵. صوت (اختیاری)متن تأییدشده به یک پیام صوتی کوتاه تبدیل می‌شود.followup-58213.mp3 برای سیستم تماس برگشتی.

سه فراخوانی API پشت این مراحل:

curl https://api.mahvashai.ir/v1/audio/transcriptions \
  -H "Authorization: Bearer $MAHVASH_PROJECT_KEY" \
  -F model="$TRANSCRIPTION_MODEL" \
  -F file=@call-58213.m4a

# Response
{ "text": "سلام، این هفته هر شب اینترنتم خیلی کند است، مخصوصاً بعد از ساعت هشت. در طول روز مشکلی ندارد. دو بار هم مودم را خاموش و روشن کرده‌ام." }

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

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

تماس در روند کاری خودتان می‌ماند

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

مهوش تماسی برقرار نمی‌کند و با مشتری شما صحبت نمی‌کند. فقط متن و صوت برمی‌گرداند و تصمیم دربارهٔ استفاده از آن‌ها با سیستم شماست.

انتخاب مدل‌های صوتی

  • با GET /v1/models یک مدل تبدیل گفتار به متن و، اگر پاسخ صوتی هم می‌خواهید، یک مدل تبدیل متن به گفتار و صدای آن را پیدا کنید.
  • API key پروژه را فقط روی سرور نگه دارید.
  • اگر پاسخ‌ها باید به سیاست‌های پشتیبانی ارجاع دهند، یک vector store شامل همان سیاست‌ها بسازید.

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

GET فهرست مدل‌های فعال ↗

تبدیل به متن، نوشتن پاسخ، تبدیل به گفتار

  1. ۱فایل ضبط‌شده را به‌صورت multipart به /v1/audio/transcriptions بفرستید و متن حاصل را ذخیره کنید.
  2. ۲بگذارید کارشناس متن را بازبینی کند یا آن را خودکار به مرحلهٔ بعد بفرستید.
  3. ۳متن را به /v1/responses بفرستید؛ در صورت نیاز همراه با file_search.
  4. ۴اگر پاسخ تأییدشده باید خوانده شود، آن را به /v1/audio/speech بفرستید تا فایل صوتی برگردد.

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

POST تبدیل فایل صوتی به متن ↗POST ساخت response ↗POST تبدیل متن به گفتار ↗

پیاده‌سازی در بک‌اند

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

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

const api = "https://api.mahvashai.ir";
const auth = { Authorization: "Bearer " + process.env.MAHVASH_PROJECT_KEY! };
const form = new FormData();
form.set("model", process.env.TRANSCRIPTION_MODEL!);
form.set("file", callRecording); // File or Blob supplied by your app
const transcript = await fetch(api + "/v1/audio/transcriptions", {
  method: "POST", headers: auth, body: form
}).then(r => r.json());
const reply = await fetch(api + "/v1/responses", {
  method: "POST", headers: { ...auth, "Content-Type": "application/json" },
  body: JSON.stringify({ model: "auto", input: "Draft an agent response to: " + transcript.text })
}).then(r => r.json());
await db.calls.saveSuggestion(callId, { transcript: transcript.text, responseId: reply.id });
// After agent approval, use the approved text for speech.
const audio = await fetch(api + "/v1/audio/speech", {
  method: "POST", headers: { ...auth, "Content-Type": "application/json" },
  body: JSON.stringify({ model: process.env.SPEECH_MODEL, voice: process.env.SPEECH_VOICE, input: approvedText })
});
await storage.save(callId, await audio.arrayBuffer());

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

{
  "text": "I need help resetting my account password."
}

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

خروجی در صفحهٔ کار کارشناس

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

وقتی فقط بخشی از کار موفق است

هر مرحله ممکن است جداگانه موفق یا ناموفق شود؛ مثلاً تبدیل به متن موفق باشد ولی نوشتن پاسخ یا ساخت فایل صوتی شکست بخورد.

  • متن تماس و همهٔ مقدارهای X-Request-ID را نگه دارید.
  • مرحلهٔ ناموفق را نشان دهید و بگذارید کارشناس کار را دستی ادامه دهد.
  • مرحلهٔ پولی‌ای را که نتیجه‌اش مشخص نیست دوباره اجرا نکنید؛ اول آن را با شناسهٔ response بازیابی کنید.

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

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