پشتیار
پشتیار
تماس خروجی

برقراری تماس خروجی

جزئیات دقیق اندپوینت ارسال تماس خروجی، فیلدهای بدنه درخواست و پاسخ‌های سرور

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

POSThttps://api.poshtyar.com/api/v1/external/calls/originate

هدرهای مورد نیاز (Headers)

Content-Type: application/json
X-API-KEY: poshtyar_live_YOUR_API_KEY_HERE

پارامترهای بدنه درخواست (Request Body)

درخواست باید با فرمت application/json ارسال شود:

فیلدنوع دادهوضعیتپیش‌فرضتوضیحات
phone_numberstringالزامی-شماره تلفن همراه، خط شهری یا داخلی سانترال (مثلاً 101 یا 2004 برای کاربران Issabel). ارقام فارسی و فاصله‌ها خودکار تصحیح می‌شوند.
operator_idstringالزامی-شناسه (ObjectID) اپراتور ساخته شده در پنل کاربری پشتیار.
recipient_namestringاختیاری""نام و نام خانوادگی مخاطب جهت خوش‌آمدگویی و شخصی‌سازی مکالمه.
topicstringاختیاری""عنوان یا موضوع تماس (مثلاً پیگیری سفارش یا یادآوری نوبت).
descriptionstringاختیاری""سناریو و توضیحات تکمیلی جهت راهنمایی دقیق هوش مصنوعی در گفتگو.
opener_textstringاختیاریمتن پیش‌فرضمتن یا جمله آغازین. پشتیبانی از متغیرهای {name} و {نام} جهت جایگذاری خودکار نام مخاطب. در حالت announcement، کل این متن به صورت صوتی خوانده می‌شود.
outbound_typestringاختیاری"ai"نوع تماس: "ai" (مکالمه تعاملی کامل با هوش مصنوعی)، "announcement" (اطلاع‌رسانی صوتی یک‌طرفه و قطع خودکار با هزینه بهینه)، یا "audio_file" (پخش فایل صوتی سفارشی).
start_modestringاختیاری"ai_first"نحوه شروع مکالمه در حالت ai: "ai_first" (شروع فوری توسط هوش مصنوعی) یا "user_first" (انتظار برای «الو» یا سلام مخاطب با پاسخگویی فوق‌سریع در لحظه).
retry_policyarray[int]اختیاری[]فواصل زمانی تلاش مجدد به ثانیه در صورت عدم پاسخگویی (مثلاً [300, 1800, 7200]).
audio_keystringشرطی""در صورت انتخاب outbound_type = "audio_file"، کلید فایل صوتی آپلود شده.

نمونه درخواست‌ها (Request Payloads)

۱. تماس گفتگوی تعاملی هوش مصنوعی (ai)

{
  "phone_number": "09123456789",
  "operator_id": "66f10c3b8417d3b5b1234567",
  "recipient_name": "علی رضایی",
  "topic": "تایید سفارش و هماهنگی ارسال",
  "description": "مشتری سفارش شماره ۱۲۴۵۰ را ثبت کرده است. از او بابت خرید تشکر کن و آدرس را تایید بگیر.",
  "opener_text": "سلام جناب {name}، وقت بخیر. از پشتیبانی فروشگاه تماس می‌گیرم در مورد سفارش شما.",
  "outbound_type": "ai",
  "start_mode": "user_first",
  "retry_policy": [300, 1800, 7200]
}

۲. تماس پیام صوتی و اطلاع‌رسانی یک‌طرفه (announcement)

در این حالت متن با مدل پیشرفته Gemini 3.8 Flash Lite TTS با بالاترین کیفیت به صوت تبدیل شده، پخش می‌شود و سپس تماس به طور خودکار قطع می‌گردد (بدون مصرف دقایق هوش مصنوعی مکالمه‌ای):

{
  "phone_number": "09123456789",
  "operator_id": "66f10c3b8417d3b5b1234567",
  "recipient_name": "سارا محمدی",
  "topic": "یادآوری نوبت دندانپزشکی",
  "opener_text": "سلام {name} عزیز وقت بخیر، نوبت شما برای فردا ساعت ۵ عصر ثبت شده است. منتظر حضور شما هستیم.",
  "outbound_type": "announcement"
}

۳. تماس با خط داخلی سانترال (Issabel PBX Extension)

{
  "phone_number": "101",
  "operator_id": "66f10c3b8417d3b5b1234567",
  "recipient_name": "واحد مالی",
  "topic": "هشدار سیستم",
  "opener_text": "سلام، فاکتورهای امروز با موفقیت صادر شدند.",
  "outbound_type": "announcement"
}

پاسخ‌های سرور (Responses)

پاسخ موفق (200 OK)

{
  "status": "success",
  "message": "تماس خروجی با موفقیت برقرار شد"
}

کدهای خطا و پاسخ‌های ناموفق

عدم ارسال شماره یا اپراتور (400 Bad Request)

{
  "error": "شماره تماس و اپراتور الزامی است"
}

کلید API نامعتبر است (401 Unauthorized)

{
  "error": "کلید API نامعتبر است"
}

عدم فعال‌بودن دسترسی وب‌سرویس (403 Forbidden)

{
  "error": "دسترسی به وب‌سرویس تماس خروجی (Outbound Call API) برای حساب کاربری شما فعال نشده است. لطفاً جهت فعال‌سازی با پشتیبانی تماس حاصل فرمایید."
}

عدم موجودی کافی در کیف پول (402 Payment Required)

{
  "error": "اعتبار حساب کافی نیست"
}

سقف تماس‌های همزمان فعال (429 Too Many Requests)

{
  "error": "تعداد تماس‌های همزمان فعال شما (۲ تماس) به سقف مجاز (۲ تماس) رسیده است. لطفاً منتظر اتمام تماس‌های جاری بمانید"
}

مانیتورینگ زنده و پیگیری وضعیت تماس

پس از ارسال درخواست:

  1. تماس در تب مانیتورینگ زنده (/dashboard/outbound) با وضعیت شماره‌گیری و مکالمه زنده نمایش داده می‌شود.
  2. در صورت فعال بودن retry_policy و عدم پاسخگویی، تلاش‌های مجدد در صف تماس‌های برنامه‌ریزی‌شده قرار می‌گیرند.
  3. پس از اتمام مکالمه، فایل صوتی، متن پیاده‌سازی‌شده (Transcript) و تحلیل در بخش تماس‌ها قابل دسترس خواهند بود.