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

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