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

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

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

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

1. إنشاء وكيل

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

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

   سمِّ كل اسم مضيف سيضمّن الأداة. ترسل المتصفحات مصدر الصفحة مع كل طلب جلسة، لذا تمنع القائمة مفتاحك من العمل عندما ينسخه شخص إلى موقع آخر. هذه ليست مصادقة: يمكن لنص برمجي خارج المتصفح إرسال أي ترويسة Origin. لا يُسمح بـ localhost تلقائيًا في بيئة الإنتاج؛ لاختباره محليًا مقابل واجهة برمجة التطبيقات للإنتاج، أضف localhost إلى القائمة.

4. اختيار تجاوزات المتصفح

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

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

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"],
    "allowed_overrides": ["context"]
  }'

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 نفسه وتعرض زر الميكروفون وعنصر الصوت أثناء المكالمة.

تجاوزات المتصفح#

يمكن للودجت إرسال أربعة إعدادات لكل جلسة من الصفحة:

مفتاحك القابل للنشر عام، لذا يمكن لأي شخص يملكه إرسال هذه الإعدادات، بما في ذلك من نص برمجي ينتحل نطاقك. ولذلك يكون كل إعداد معطلاً إلى أن تسمح به على المفتاح: فعِّله ضمن تجاوزات المتصفح عند إنشاء الأداة أو تعديلها في لوحة التحكم، أو اضبط allowed_overrides عبر واجهة برمجة تطبيقات المفاتيح القابلة للنشر. اسمح فقط بما ترسله صفحتك فعلياً.

يفشل طلب الجلسة الذي يحمل إعدادًا لا يسمح به المفتاح برمز 400 ويذكر اسمه:

{
  "error": "override_not_allowed",
  "fields": ["voice"],
  "message": "This publishable key does not allow the browser to set `voice`. ..."
}

ينطبق الفحص في كلا الوضعين. في وضع webhook، يُعاد توجيه الإعداد المسموح به أيضًا إلى webhook web.incoming الخاص بك (يصل context باسم website_context). تسمح المفاتيح التي أُنشئت قبل وجود هذا الإعداد بالإعدادات الأربعة كلها، لذا تستمر التضمينات الحالية في العمل؛ عطّل ما لا تستخدمه.

يُقتطع 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 لإنشاء لوحة معلومات خاصة بالودجت فقط.

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