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

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

<Note>
  תוכלו לבצע את כל הפעולות האלה ללא cURL: דף לוח הבקרה **וידג'טים לאינטרנט**
  (`/dashboard/web-widgets`) יוצר את הווידג'ט, מגדיר את המצב
  והסוכן שלו, מנהל דומיינים מורשים ומספק לכם את קטע ההטמעה.
</Note>

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

<Steps>
  <Step title="צרו סוכן">
    הסוכן שההנחיה והקול שלו יפעילו את סשן הווידג'ט. הגדירו
    `widget_enabled: true` (ברירת המחדל).
  </Step>
  <Step title="החליטו על מצב הניתוב">
    - `mode="agent"` — סוכן סטטי אחד לכל מפתח. הפשוט ביותר.
    - `mode="webhook"` — השרת שלכם בוחר את הסוכן לכל מבקר באמצעות
      [וובהוק `web.incoming`](/he/webhooks/call-incoming). השתמשו בכך עבור
      משתמשים מחוברים, בדיקות A/B או ניתוב לפי עמוד.
  </Step>
  <Step title="רשמו את הדומיינים המורשים">
    ציינו כל שם מארח שיטמיע את הווידג'ט. דפדפנים שולחים את
    מקור העמוד עם כל בקשת סשן, לכן הרשימה מונעת מהמפתח שלכם
    לפעול כאשר מישהו מעתיק אותו לאתר אחר. זה אינו
    אימות: תוכנית מחוץ לדפדפן יכולה לשלוח כל כותרת `Origin`.
    `localhost` אינו מורשה אוטומטית בייצור; כדי
    לבדוק באופן מקומי מול API הייצור, הוסיפו את `localhost` אל
    הרשימה.
  </Step>
  <Step title="בחרו את עקיפות הדפדפן">
    החליטו אילו הגדרות סשן העמוד שלכם רשאי לשלוח. מפתחות חדשים אינם מקבלים
    עקיפות; ראו [עקיפות דפדפן](#browser-overrides).
  </Step>
</Steps>

## יצירת מפתח לפרסום

<CodeGroup>
```bash Static agent
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"]
  }'
```

```bash Dynamic via webhook
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"]
  }'
```
</CodeGroup>

התגובה כוללת `key` שמתחיל ב-`pk_live_...`. **מפתחות לפרסום
הם ציבוריים בכוונה תחילה** — בטוח לכלול אותם בחבילת הקצה הקדמי שלכם.
ראו את [תיעוד מפתחות לפרסום](/api-reference/publishable-keys) עבור
כל השדות.

<Warning>
  `allowed_domains` חייב להכיל לפחות רשומה אחת. `*.example.com`
  תואם לתת-דומיינים (למשל `api.example.com`) אך **לא** לדומיין
  הבסיסי. תווים כלליים בסיסיים כגון `*` או `*.*` נדחים.
</Warning>

## הוספת הווידג'ט לאתר שלכם

שלוש אפשרויות אינטגרציה מתוארות ב-
[תיעוד SDK של הווידג'ט](/he/widget/overview):

<CardGroup cols={3}>
  <Card title="רכיב React" icon="react" href="/he/widget/react">
    `<ThunderPhoneWidget publishableKey="pk_live_..." />`.
  </Card>
  <Card title="הוק ללא ממשק" icon="circle-nodes" href="/he/widget/headless-hook">
    `useThunderPhone()` עבור ממשקי משתמש מותאמים אישית.
  </Card>
  <Card title="תגית סקריפט CDN" icon="code" href="/he/widget/cdn-script-tag">
    `ThunderPhone.mount({...})` עבור אתרים ללא מאגד.
  </Card>
</CardGroup>

כל שלוש האפשרויות מקבלות את אותו `publishableKey` ומציגות את כפתור
המיקרופון ואת רכיב השמע במהלך השיחה.

## עקיפות מהדפדפן

הווידג'ט יכול לשלוח ארבע הגדרות לכל סשן מהדף:

| הגדרה | מאפיין וידג'ט | מה היא משנה |
|---------|-------------|-----------------|
| `context` | `context` | טקסט מהדף, שמתווסף להנחיית הסוכן כחומר עזר |
| `variables` | ללא (רק `POST /v1/widget/session` גולמי) | ערכים עבור מצייני מיקום `{{variable}}` בהנחיה |
| `voice` | `voice` | קול הסוכן עבור סשן זה |
| `language` | `language` | השפה שבה הסשן מתחיל |

מפתח הפרסום שלכם הוא ציבורי, לכן כל מי שיש לו אותו יכול לשלוח את ההגדרות האלה, כולל מסקריפט שמתחזה לדומיין שלכם. לכן כל אחת מהן מושבתת עד שתאפשרו אותה במפתח: סמנו אותה תחת **עקיפות דפדפן** כשאתם יוצרים או עורכים את הווידג'ט בלוח הבקרה, או הגדירו את `allowed_overrides` באמצעות [API של מפתחות פרסום](/api-reference/publishable-keys). אפשרו רק את מה שהדף שלכם שולח בפועל.

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

```json
{
  "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
אסימונים של טקסט אנגלי טיפוסי) ונכלל במסגרת
[תוספת התשלום על גודל ההנחיה](/he/guides/billing-and-topups).
הסוכן מונחה להתייחס אליו כתוכן דף, ולא כהוראות.

## וובהוקים במצב וידג'ט

כאשר `mode="webhook"`, ThunderPhone קוראת ל-`webhook_url` שלכם בכל
תחילת הפעלה עם מטען `web.incoming`. החזירו את תצורת הסוכן
שברצונכם להפעיל עבור אותו מבקר — היא פועלת לפי אותה
[סכמת תגובה](/he/webhooks/call-incoming) כמו שיחות
טלפון:

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

תוכלו לשלב בהנחיה הקשר מההפעלה שלכם (איזה לקוח גולש,
באיזה עמוד הוא נמצא), ולהחליף סוכנים לפי פריסה.

## עקבו אחר ההפעלות

הפעלות של הווידג'ט מופיעות ב-
[`GET /v1/calls`](/api-reference/calls#list-calls) עם
`direction="widget"` — עם אותו תמלול, הקלטה, דירוג וחיוב
כמו שיחות טלפון. סננו לפי `direction` כדי לבנות לוח בקרה
לווידג'ט בלבד.

---

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

<CardGroup cols={2}>
  <Card title="הפניית SDK של הווידג'ט" icon="window-maximize" href="/he/widget/overview">
    פרטי שילוב של React / hook / CDN.
  </Card>
  <Card title="תצורה דינמית לכל שיחה" icon="bolt" href="/he/guides/dynamic-call-config">
    הטמיעו את התהליך `mode="webhook"` מקצה לקצה.
  </Card>
  <Card title="הפניית מפתחות ניתנים לפרסום" icon="key" href="/api-reference/publishable-keys">
    כל שדה במשאב המפתח.
  </Card>
  <Card title="API של הפעלות מיקרופון" icon="microphone" href="/api-reference/mic-sessions">
    דלגו על הווידג'ט; הפעילו את LiveKit ישירות עבור ממשקי משתמש מותאמים אישית.
  </Card>
</CardGroup>