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