Skip to main content
توفّر أداة الويب لزوار موقعك محادثة بالنقر للتحدث مع وكيل ذكاء اصطناعي، باستخدام ميكروفون المتصفح. وهي حزمة تطوير برمجيات منفصلة لـ JavaScript / React ولها مرجع حزمة تطوير البرامج الخاص بها — يركّز هذا الدليل على الإعدادات في ThunderPhone التي تحتاجها أداة الويب.
يمكنك تنفيذ كل ذلك دون cURL: إذ تنشئ صفحة لوحة التحكم أدوات الويب (/dashboard/web-widgets) الأداة، وتضبط وضعها ووكيلها، وتدير النطاقات المسموح بها، وتزوّدك بمقتطف التضمين.

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

1

إنشاء وكيل

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

تحديد وضع التوجيه

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

إدراج النطاقات المسموح بها

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

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

تتضمن الاستجابة key يبدأ بـ pk_live_.... المفاتيح القابلة للنشر عامة حسب التصميم — ومن الآمن تضمينها في حزمة الواجهة الأمامية. راجع مرجع المفاتيح القابلة للنشر للاطلاع على جميع الحقول.
يجب أن يحتوي allowed_domains على إدخال واحد على الأقل. يطابق *.example.com النطاقات الفرعية (مثل api.example.com) ولكنه لا يطابق النطاق المجرد. تُرفض أحرف البدل المجردة مثل * أو *.*.

​
أضف أداة الويب إلى موقعك

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

مكوّن React

<ThunderPhoneWidget publishableKey="pk_live_..." />.

خطاف بلا واجهة

useThunderPhone() لواجهات المستخدم المخصصة.

وسم برنامج CDN النصي

ThunderPhone.mount({...}) للمواقع التي لا تستخدم حزمًا.
تقبل الخيارات الثلاثة نفسها publishableKey وتعرض زر الميكروفون بالإضافة إلى عنصر الصوت أثناء المكالمة. يُقتطع context الخاص بأداة الويب عند 12,000 حرف (نحو 3,400 رمز من نص إنجليزي نموذجي) ويُحتسب ضمن الرسوم الإضافية لحجم الموجّه.

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

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

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

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

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

مرجع SDK الأداة

تفاصيل التكامل مع React / hook / CDN.

إعدادات ديناميكية لكل مكالمة

نفّذ تدفق mode="webhook" بالكامل.

مرجع المفاتيح القابلة للنشر

كل حقل في مورد المفتاح.

واجهة API لجلسات الميكروفون

تجاوز الأداة؛ واستخدم LiveKit مباشرةً لواجهات مستخدم مخصصة.