Developer cookbook

تضمين أداة الويب

أضف وكيلاً صوتياً إلى موقعك التسويقي أو موقع الدعم باستخدام وسم برمجي واحد — يتحدث الزوار إليه مباشرةً من المتصفح، من دون الحاجة إلى رقم هاتف.

تمنح أداة الويب زوّار موقعك محادثة بالنقر للتحدث مع وكيل ذكاء اصطناعي، باستخدام ميكروفون المتصفح. وهي حزمة SDK مستقلة بلغة JavaScript / React لها مرجع SDK خاص بها — يركّز هذا الدليل على إعدادات ThunderPhone التي تحتاجها الأداة.

المتطلبات المسبقة#

1. إنشاء وكيل

   الوكيل الذي سيشغّل موجّهه وصوته جلسة الأداة. اضبط widget_enabled: true (القيمة الافتراضية).

2. تحديد وضع التوجيه
   • mode="agent" — وكيل ثابت واحد لكل مفتاح. وهو الأبسط.
   • mode="webhook" — يختار خادمك الوكيل لكل زائر عبر خطاف ويب web.incoming. استخدم هذا للمستخدمين المسجّلين، واختبارات A/B، أو التوجيه لكل صفحة.
3. إدراج النطاقات المسموح بها

   المفاتيح القابلة للنشر مقيّدة بالمصدر. يجب أن تسمّي كل اسم مضيف سيضمّن الأداة. يُسمح دائمًا بـ localhost / 127.0.0.1 أثناء التطوير المحلي.

إنشاء مفتاح قابل للنشر#

curl -X POST https://api.thunderphone.com/v1/publishable-key \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name":            "Marketing site (prod)",
    "mode":            "agent",
    "agent_id":        12,
    "allowed_domains": ["example.com", "*.example.com"]
  }'

curl -X POST https://api.thunderphone.com/v1/publishable-key \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name":            "Support (dynamic)",
    "mode":            "webhook",
    "webhook_url":     "https://example.com/thunderphone/widget-hook",
    "allowed_domains": ["support.example.com"]
  }'

تتضمن الاستجابة key يبدأ بـ pk_live_.... المفاتيح القابلة للنشر عامة بطبيعتها — ومن الآمن تضمينها في حزمة الواجهة الأمامية. راجع مرجع المفاتيح القابلة للنشر للاطلاع على جميع الحقول.

أضف الأداة إلى موقعك#

تغطي وثائق SDK للأداة ثلاثة خيارات للتكامل:

تقبل الخيارات الثلاثة جميعها publishableKey نفسه وتعرض زر الميكروفون وعنصر الصوت أثناء المكالمة.

يُقتطع context الخاص بالأداة عند 12,000 حرف (نحو 3,400 رمزًا من النص الإنجليزي المعتاد) ويُحتسب ضمن الرسوم الإضافية لحجم الموجّه.

خطافات ويب وضع الأداة#

عندما يكون mode="webhook"، يستدعي ThunderPhone عنوان webhook_url في كل بداية جلسة بحمولة web.incoming. أعد إعدادات الوكيل التي تريد تشغيلها لذلك الزائر — فهي تتبع مخطط الاستجابة نفسه الخاص بالمكالمات الهاتفية:

{
  "prompt":  "You are a VIP concierge for Jane Doe.",
  "voice":   "john",
  "product": "storm-base",
  "tools":   [ /* per-customer tools */ ]
}

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

راقب الجلسات#

تظهر جلسات الودجت في GET /v1/calls مع direction="widget" — وبنفس النص المفرغ والتسجيل والتقييم والفوترة الخاصة بالمكالمات الهاتفية. صفِّ حسب direction لإنشاء لوحة معلومات خاصة بالودجت فقط.

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