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

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

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

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

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الزامی-شماره تلفن همراه یا ثابت مقصد (ارقام فارسی و فاصله‌ها خودکار تصحیح می‌شوند).
operator_idstringالزامی-شناسه (ObjectID) اپراتور ساخته شده در پنل کاربری پشتیار.
recipient_namestringاختیاری""نام و نام خانوادگی مخاطب جهت خوش‌آمدگویی و شخصی‌سازی مکالمه.
topicstringاختیاری""عنوان یا موضوع تماس (مثلاً پیگیری سفارش یا یادآوری نوبت).
descriptionstringاختیاری""سناریو و توضیحات تکمیلی جهت راهنمایی دقیق هوش مصنوعی در گفتگو.
opener_textstringاختیاریمتن پیش‌فرضجمله آغازین دستیار صوتی بلافاصله پس از برداشتن گوشی توسط مخاطب.
retry_policyarray[int]اختیاری[]فواصل زمانی تلاش مجدد به ثانیه در صورت عدم پاسخگویی (مثلاً [300, 1800, 7200]).
outbound_typestringاختیاری"ai"نوع تماس: "ai" (مکالمه تعاملی هوش مصنوعی) یا "audio_file" (پخش فایل صوتی).
audio_keystringشرطی""در صورت انتخاب outbound_type = "audio_file"، کلید فایل صوتی آپلود شده.

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

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

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

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

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

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

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

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

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

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

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

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

عدم موجودی کافی در کیف پول (500 Internal Server Error)

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

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

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

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