تماس خروجی
برقراری تماس خروجی
جزئیات دقیق اندپوینت ارسال تماس خروجی، فیلدهای بدنه درخواست و پاسخهای سرور
از این وبسرویس برای ارسال درخواست برقراری تماس تلفنی هوشمند با شماره مورد نظر استفاده میشود. با فراخوانی این اندپوینت، سیستم تلفنی پشتیار با مخاطب تماس گرفته و به محض برداشتن گوشی، اپراتور هوش مصنوعی مکالمه را طبق سناریوی ارسالی هدایت میکند.
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_number | string | الزامی | - | شماره تلفن همراه یا ثابت مقصد (ارقام فارسی و فاصلهها خودکار تصحیح میشوند). |
operator_id | string | الزامی | - | شناسه (ObjectID) اپراتور ساخته شده در پنل کاربری پشتیار. |
recipient_name | string | اختیاری | "" | نام و نام خانوادگی مخاطب جهت خوشآمدگویی و شخصیسازی مکالمه. |
topic | string | اختیاری | "" | عنوان یا موضوع تماس (مثلاً پیگیری سفارش یا یادآوری نوبت). |
description | string | اختیاری | "" | سناریو و توضیحات تکمیلی جهت راهنمایی دقیق هوش مصنوعی در گفتگو. |
opener_text | string | اختیاری | متن پیشفرض | جمله آغازین دستیار صوتی بلافاصله پس از برداشتن گوشی توسط مخاطب. |
retry_policy | array[int] | اختیاری | [] | فواصل زمانی تلاش مجدد به ثانیه در صورت عدم پاسخگویی (مثلاً [300, 1800, 7200]). |
outbound_type | string | اختیاری | "ai" | نوع تماس: "ai" (مکالمه تعاملی هوش مصنوعی) یا "audio_file" (پخش فایل صوتی). |
audio_key | string | شرطی | "" | در صورت انتخاب 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": "اعتبار حساب کافی نیست"
}مانیتورینگ زنده و پیگیری وضعیت تماس
پس از ارسال درخواست:
- تماس در تب مانیتورینگ زنده (
/dashboard/outbound) با وضعیت شمارهگیری و مکالمه زنده نمایش داده میشود. - در صورت فعال بودن
retry_policyو عدم پاسخگویی، تلاشهای مجدد در صف تماسهای برنامهریزیشده قرار میگیرند. - پس از اتمام مکالمه، فایل صوتی، متن پیادهسازیشده (Transcript) و تحلیل در بخش تماسها قابل دسترس خواهند بود.