Developer cookbook

إجراء مكالمات صادرة (API)

شغّل مكالمة صادرة مدعومة بالذكاء الاصطناعي من شفرتك البرمجية — لاستطلاعات الرأي أو المتابعة أو مسارات التأكيد.

تتيح لك المكالمات الصادرة تمرير رقم وجهة وإعداد وكيل إلى ThunderPhone ليجري الذكاء الاصطناعي المكالمة نيابةً عنك. حالات الاستخدام المعتادة:

• تأكيدات المواعيد
• معاودة الاتصال للاستبيانات
• متابعات «المحاولة الثانية» بعد مكالمة فائتة
• إشعارات بأسلوب الإرسال

المتطلبات الأساسية#

1. أحضر رقم VoIP

   تتطلب المكالمات الصادرة أن تمتلك from_number عبر اتصال VoIP. أرقام العرض التوضيحي مخصصة للمكالمات الواردة فقط. راجع أحضر أرقامك الخاصة.

2. أنشئ وكيلاً

   يميل الموجّه المخصص للمكالمات الصادرة إلى البدء بتعريف الوكيل بنفسه وبغرضه — «مرحباً، معك Acme للاتصال لتأكيد موعدك غداً الساعة 3 مساءً…». اضبط outbound_speak_order على agent_first (القيمة الافتراضية).

3. حافظ على رصيد موجب

   تُرجع المكالمات الصادرة 402 Payment Required إذا كان الرصيد ≤ $0.00. اشحن الرصيد عبر POST /v1/billing/top-up أو فعّل إعادة الشحن التلقائي.

أجرِ مكالمة باستخدام وكيل محفوظ#

أبسط طريقة — الإشارة إلى وكيل عبر معرّفه:

curl -X POST https://api.thunderphone.com/v1/call \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from_number": "+15551234567",
    "to_number":   "+14155550199",
    "agent_id":    12
  }'

الاستجابة:

{ "call_id": 987654321, "status": "initiated" }

أجرِ مكالمة بإعداد مضمن#

إذا أردت موجّهاً لمرة واحدة لا يستحق الحفظ كوكيل، فمرر config بدلاً من ذلك. يتطابق الشكل مع مخطط الاستجابة لخطاف الويب call.incoming:

curl -X POST https://api.thunderphone.com/v1/call \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from_number": "+15551234567",
    "to_number":   "+14155550199",
    "config": {
      "prompt":  "You are confirming Jane Doe appointment for 3pm tomorrow…",
      "voice":   "john",
      "product": "spark"
    }
  }'

تابع المكالمة#

بالتوازي، اشترك في خطاف الويب telephony.complete — وهو أسرع طريقة لمعرفة انتهاء المكالمة. إذا لم تتمكن من استقبال خطافات الويب الواردة، فاستعلم دورياً عن GET /v1/calls/{call_id} كل بضع ثوانٍ؛ يتضمن السجل end_reason وduration_seconds ورابط التسجيل عند انتهاء المكالمة.

حالات الفشل التي تستحق المعالجة#

التحكم في مدة الانتظار#

يمكن تحديد حد أقصى للمكالمات الصادرة التي تطول لأن الطرف المتصل به بطيء في الاستجابة (قوائم IVR، قوائم الانتظار) باستخدام max_hold_seconds:

{
  "from_number": "+15551234567",
  "to_number":   "+14155550199",
  "agent_id":    12,
  "max_hold_seconds": 120
}

ينهي الوكيل المكالمة إذا لم يتم تلقي أي صوت بشري خلال آخر N ثانية. القيمة الافتراضية هي 900 (15 دقيقة).

الخطوات التالية#