הטמעת הווידג

הוסיפו סוכן קולי לאתר השיווק או התמיכה שלכם באמצעות תג סקריפט יחיד — המבקרים יכולים לדבר איתו ישירות מהדפדפן, ללא צורך במספר טלפון.

וידג'ט האינטרנט מעניק למבקרים באתר שלכם שיחה בלחיצה כדי לדבר עם סוכן בינה מלאכותית, באמצעות המיקרופון של הדפדפן. זהו SDK נפרד של JavaScript / React עם תיעוד SDK משלו — מדריך זה מתמקד בהגדרה בצד של ThunderPhone שהווידג'ט זקוק לה.

דרישות מקדימות#

1. צרו סוכן

   הסוכן שההנחיה והקול שלו יפעילו את סשן הווידג'ט. הגדירו widget_enabled: true (ברירת המחדל).

2. החליטו על מצב הניתוב
   • mode="agent" — סוכן סטטי אחד לכל מפתח. הפשוט ביותר.
   • mode="webhook" — השרת שלכם בוחר את הסוכן לכל מבקר באמצעות וובהוק web.incoming. השתמשו בכך עבור משתמשים מחוברים, בדיקות A/B או ניתוב לפי עמוד.
3. רשמו את הדומיינים המורשים

   ציינו כל שם מארח שיטמיע את הווידג'ט. דפדפנים שולחים את מקור העמוד עם כל בקשת סשן, לכן הרשימה מונעת מהמפתח שלכם לפעול כאשר מישהו מעתיק אותו לאתר אחר. זה אינו אימות: תוכנית מחוץ לדפדפן יכולה לשלוח כל כותרת Origin. localhost אינו מורשה אוטומטית בייצור; כדי לבדוק באופן מקומי מול API הייצור, הוסיפו את 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 באמצעות API של מפתחות פרסום. אפשרו רק את מה שהדף שלכם שולח בפועל.

בקשת סשן הכוללת הגדרה שהמפתח אינו מאפשר נכשלת עם 400 ומציינת אותה:

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

הבדיקה חלה בשני המצבים. במצב וובהוק, הגדרה מותרת מועברת גם לוובהוק 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 כדי לבנות לוח בקרה לווידג'ט בלבד.

השלבים הבאים#