معالجة المكالمات الواردة (API)

من البداية إلى النهاية: هيّئ وكيلاً صوتياً، وعيّنه لرقم هاتف، وتلقَّ مكالمة، وافحص النص المفرغ.

التدفق القياسي لـ «الرد على هاتف بالذكاء الاصطناعي» من طرفيتك. ستقوم بما يلي:

1. إنشاء وكيل باستخدام موجّه وصوت.
2. توفير رقم هاتف (أو إحضار رقمك) وتعيين الوكيل كمعالج للمكالمات الواردة.
3. الاتصال بالرقم. راقب سجل المكالمات، والنص المفرغ، والتسجيل.

إجمالي استدعاءات API: أربعة. الوقت الإجمالي: أقل من خمس دقائق.

1. أنشئ وكيلًا#

يجمع الوكيل بين الموجّه والصوت ومستوى المنتج الذي سيدير المكالمة. يمكنك أيضًا ضبط حدود المكالمات، مثل max_call_duration_seconds وring_duration_seconds، على الوكيل. يدعم الوكلاء كذلك intro_clip وintro_ring_count لتشغيل مقدمة مسجلة مسبقًا وما يصل إلى رنتين قبل أن يتحدث الوكيل. تحتاج الوكلاء الجديدة أيضًا إلى منطقة زمنية. إذا كان وكيلك متعدد اللغات، يمكنك ضبط language_switching للتحكم في ما إذا كان يسأل قبل تبديل اللغات أو يتبع لغة المتصل. راجع الوكلاء للاطلاع على كل حقل إعداد؛ والحد الأدنى هو:

curl -X POST https://api.thunderphone.com/v1/agents \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name":    "Acme Support",
    "prompt":  "You are a friendly support agent for Acme. Help callers with orders and returns. Keep answers short.",
    "voice":   "john",
    "product": "spark"
  }'

احفظ قيمة id المعادة — ستحتاج إليها في الخطوة 2.

2. احصل على رقم هاتف#

إذا كنت تحتاج فقط إلى رقم للاتصال به، فاحصل على رقم ThunderPhone من مجموعة أرقام ThunderPhone:

curl -X POST https://api.thunderphone.com/v1/phone-numbers \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"area_code": "415"}'

تتضمن الاستجابة id وnumber بتنسيق E.164. تبدأ أرقام ThunderPhone بالحالة status="provisioning" وتصبح active خلال بضع ثوانٍ — استعلم دوريًا عن GET /v1/phone-numbers/{id} لمراقبة الانتقال إذا كان ذلك يهمك.

3. عيّن الوكيل#

اربط الوكيل من الخطوة 1 باتجاه المكالمات الواردة للرقم:

curl -X PATCH https://api.thunderphone.com/v1/phone-numbers/{phone_id} \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"inbound_agent_id": 12}'

هذا كل شيء — الرقم نشط. بعد الموافقة على الاتصال الصادر لمؤسستك، يمكنك أيضًا ضبط outbound_agent_id في طلب PATCH نفسه. وحتى ذلك الحين، ترفض واجهة API هذا التعيين بالرمز 400.

إذا وجّهت المكالمات الواردة عبر خطاف ويب للإعدادات بدلاً من inbound_agent_id ثابت، يمكن لخطاف الويب هذا الآن إرجاع timezone لكل مكالمة إلى جانب agent_id وvariables.

4. استقبل مكالمة#

اتصل بالرقم من هاتفك. يرد الوكيل، ويعرّف بنفسه وفقًا لموجّهك، وتبدأ المحادثة.

أثناء سير المكالمة، تظهر في GET /v1/calls مع status="in_progress". وعند انتهائها، يُحدَّث السجل بقيم end_reason وduration_seconds وbillable_minutes، و(في النهاية) رابط تسجيل ودرجة من الذكاء الاصطناعي.

تُحتسب المكالمات الواردة ضمن حد المكالمات المتزامنة لمؤسستك (20 مكالمة قيد التنفيذ افتراضيًا، مشتركة مع المكالمات الصادرة ومكالمات الويب والاختبار). يُرفض أي اتصال يصل عند بلوغ الحد قبل أن يجيب الموجّه، ثم يُنهى، ولا تُفرض عليه رسوم، ويُسجَّل كمكالمة فاشلة بسبب إنهاء concurrent_call_limit_reached. أرسل بريدًا إلكترونيًا إلى support@thunderphone.com إذا كنت تحتاج إلى حد أعلى.

5. افحص النتائج#

اجلب قائمة المكالمات الأخيرة:

curl 'https://api.thunderphone.com/v1/calls?limit=5' \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

اجلب النص المفرغ:

curl https://api.thunderphone.com/v1/calls/{call_id}/transcript \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

ورابط التسجيل (موقّع وقصير العمر):

curl https://api.thunderphone.com/v1/calls/{call_id}/audio \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

إذا اشتركت في خطاف الويب telephony.complete فستتلقى البيانات نفسها كطلب POST إلى خادمك — راجع call.complete.

إذا كان وكيلك يضم حقول استخراج مُعدّة، فقد تتضمن حمولة المكالمة المكتملة أيضًا بيانات مستخرجة ومنظَّمة.

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