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

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

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

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

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

1. اختر رقماً مفعّلاً للمكالمات الصادرة

   استخدم رقماً تملكه عبر اتصال VoIP، أو اطلب الإذن لاستخدام أرقام ThunderPhone الخاصة بك للمكالمات الصادرة من صفحة أرقام الهاتف. تبدأ أرقام ThunderPhone مخصصة للمكالمات الواردة فقط. تراجع ThunderPhone كل طلب يدوياً؛ وبعد الموافقة، يمكن لتلك الأرقام إجراء مكالمات حتى الحد اليومي المعتمد (يُعاد ضبطه عند 00:00 UTC) وتشغيل الحملات، ويمكنك طلب حد أعلى. لا تملك أرقام VoIP الخاصة بالعملاء حداً يومياً، لذا نوصي بها للمكالمات الصادرة. راجع استخدم أرقامك الخاصة.

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

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

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

   تُرجع المكالمات الصادرة 402 Payment Required إذا كان الرصيد ≤ $0.00. أضف رصيداً أو فعّل إعادة التعبئة التلقائية ضمن المؤسسة ← إعدادات الفوترة في لوحة التحكم. يمكن لمفتاح sk_live_ الخاص بك التحقق من الرصيد باستخدام GET /v1/billing، لكنه لا يمكنه إضافة رصيد أو تغيير إعادة التعبئة التلقائية.

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

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

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":   "+14155552671",
    "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":   "+14155552671",
    "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 ورابط التسجيل بعد انتهاء المكالمة.

إذا كان وكيلك مُعدًّا لاستخراج بيانات منظّمة بعد المكالمة، تُسلَّم تلك البيانات بشكل منفصل بعد اكتمال الإنهاء.

تمرير متغيرات لكل مكالمة إلى وكيل محفوظ#

يمكن للوكلاء المحفوظين استخدام عناصر نائبة مثل {{name}} أو {{name|there}} في نص الموجّه. عند إجراء مكالمة صادرة باستخدام agent_id، مرّر variables بالقيم الخاصة بتلك المكالمة:

{
  "from_number": "+[REDACTED_PHONE]",
  "to_number": "+[REDACTED_PHONE]",
  "agent_id": 12,
  "variables": {
    "name": "Jordan"
  }
}

استخدم قيماً نصية بمفاتيح تحمل أسماء العناصر النائبة. تنطبق هذه المتغيرات على الوكلاء المحفوظين؛ ولا يستخدم مثال config المضمّن في هذا الدليل هذه المتغيرات.

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

راجع مرجع المكالمات الصادرة للاطلاع على القائمة الكاملة المستقرة لرموز الأهلية وكلا شكلي استجابة 409. إذا أصبح رقم نشط غير مؤهل بعد قبول الطلب وقبل إجراء المكالمة، يعيد الفحص النهائي حمولة 409 غير القابلة لإعادة المحاولة.

التحكم في وقت الانتظار#

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

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

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

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