Developer cookbook

التعامل مع المكالمات الواردة (واجهة برمجة التطبيقات)

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

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

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

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

1. إنشاء وكيل#

يجمع الوكيل الموجّه والصوت ومستوى المنتج الذي سيدير المكالمة. راجع الوكلاء للاطلاع على كل حقل إعداد؛ والحد الأدنى هو:

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:

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. تبدأ الأرقام التجريبية بالحالة 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 نفسه ليصبح الرقم جاهزًا لإجراء المكالمات الصادرة أيضًا.

4. تلقّي مكالمة#

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

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

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.

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