---
title: "וידג'ט קולי שניתן להטמיע"
description: "הוסיפו סוכן AI קולי לכל אתר באמצעות כמה שורות קוד"
---

רכיב הווידג'ט הקולי המוטמע של ThunderPhone מאפשר למבקרים באתר שלכם לדבר עם סוכן AI ישירות מהדפדפן. אין צורך בשיחת טלפון -- המשתמשים לוחצים על לחצן ומתחילים שיחה קולית בזמן אמת המופעלת באמצעות ThunderPhone.

הווידג'ט מוצג כסרגל במראה זכוכית המותאם לערכות נושא בהירות וכהות, עם צבעי הדגשה ומיקום הניתנים להתאמה אישית. הוא מופץ כחבילת npm `@thunderphone/widget` וזמין גם דרך CDN עבור סביבות ללא מאגד מודולים.

<Frame>
  <img src="/images/widget-showcase.png" alt="ווידג'ט ThunderPhone בערכות נושא בהירות וכהות עם מגוון צבעי הדגשה" />
</Frame>

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

לפני הטמעת הווידג'ט, השלימו את שלושת השלבים הבאים ב-[לוח הבקרה של ThunderPhone](https://app.thunderphone.com):

<Steps>
<Step title="צרו וידג'ט אינטרנט">
  עברו אל **וידג'טים לאינטרנט** בלוח הבקרה וצרו וידג'ט. בחרו את הסוכן שברצונכם לחשוף. לכל וידג'ט יש מפתח לפרסום משלו (`pk_live_...`), שאפשר לכלול בבטחה בקוד צד לקוח; הסוכן נקבע לפי המפתח.
</Step>

<Step title="הגדירו דומיינים מורשים">
  באותו וידג'ט, הוסיפו את הדומיינים שבהם הוא יוטמע. תווי כללי נתמכים (לדוגמה, `*.example.com`). הרשימה מונעת מהווידג'ט לפעול כאשר מישהו מעתיק את המפתח שלכם לאתר אחר; זו אינה אימות, משום שסקריפט מחוץ לדפדפן יכול לשלוח כל כותרת `Origin`. `localhost` אינו מורשה אוטומטית בייצור: הוסיפו אותו לרשימה כדי לבדוק באופן מקומי מול ה-API של הייצור.
</Step>

<Step title="בחרו דריסות דפדפן">
  אם הדף שלכם מגדיר `language`, `voice` או `context`, הפעילו כל אחת מהן תחת **דריסות דפדפן**. וידג'טים חדשים אינם מקבלים אף אחת מהן, ובקשת סשן הכוללת הגדרה שאינה מופעלת נכשלת עם `400 override_not_allowed`. ראו [דריסות דפדפן](/he/guides/embed-web-widget).
</Step>
</Steps>

<Warning>
  מפתחות שניתנים לפרסום (`pk_live_...`) **אינם** זהים לאסימוני ה-API הסודיים שלכם. מפתחות שניתנים לפרסום מיועדים לשימוש בצד הלקוח ומוגבלים להפעלות ווידג'ט בדומיינים המורשים שלכם. לעולם אל תשתמשו באסימון ה-API הסודי שלכם בקוד בצד הלקוח.
</Warning>

<Note>
  סשני וידג'ט מסתיימים לאחר 30 דקות כברירת מחדל, או מוקדם יותר אם משך השיחה המרבי של הסוכן קצר יותר. שנו את המגבלה לכל מפתח באמצעות `max_call_duration_seconds` ב[מפתח לפרסום](/api-reference/publishable-keys) (עד 6 שעות), או הגדירו אותו כ-`null` כדי להשתמש במגבלה של הסוכן עצמו.
</Note>

---

## התחלה מהירה

התקינו את החבילה:

```bash
npm install @thunderphone/widget
```

הוסיפו את הווידג'ט לאפליקציה שלכם:

```tsx
import { ThunderPhoneWidget } from '@thunderphone/widget'
import '@thunderphone/widget/style.css'

function App() {
  return (
    <ThunderPhoneWidget
      publishableKey="pk_live_your_publishable_key"
      theme="dark"
      primaryColor="#8b5cf6"
    />
  )
}
```

זה הכול. המשתמשים שלכם יראו סרגל שיחה במראה זכוכית שמחבר אותם לסוכן ה-AI שלכם בלחיצה אחת.

---

## התאמה אישית

לווידג'ט יש ארבעה מאפייני מראה:

| מאפיין | ברירת מחדל | תיאור |
|------|---------|-------------|
| `theme` | `'light'` | `'light'` עבור זכוכית לבנה, `'dark'` עבור זכוכית כהה |
| `primaryColor` | `'#000000'` (בהיר) / `'#ffffff'` (כהה) | צבע הדגשה ללחצן ההתחלה, לצורת הגל ולמחוון ההתחברות |
| `title` | `'Voice assistant'` | הטקסט שמוצג בווידג'ט |
| `position` | `'bottom-right'` | פינת חלון התצוגה: `'bottom-right'`, `'bottom-left'`, `'top-right'`, `'top-left'` |

<CodeGroup>
```tsx Light theme (default)
<ThunderPhoneWidget
  publishableKey="pk_live_your_publishable_key"
/>
```

```tsx Dark theme with custom color
<ThunderPhoneWidget
  publishableKey="pk_live_your_publishable_key"
  theme="dark"
  primaryColor="#8b5cf6"
  title="Ask our AI"
/>
```
</CodeGroup>

שלושה מאפיינים נוספים מתאימים את ההפעלה ולא את המראה -- כולם מועברים לבקשת ההפעלה כאשר שיחה מתחילה. כל אחד מהם פועל רק כאשר המפתח הציבורי של הווידג'ט מאפשר זאת תחת **דריסות דפדפן**; אחרת בקשת ההפעלה נכשלת עם `400 override_not_allowed`:

| מאפיין | תיאור |
|------|-------------|
| `language` | דריסת שפה לכל הפעלה -- קוד או אזור כגון `en`, `es` או `fr-FR` |
| `voice` | דריסת קול לכל הפעלה -- שם קול כגון `maria` |
| `context` | הקשר עובדתי של הדף או האתר שמועבר לסוכן (מקוצר בצד השרת ל-12,000 תווים) |

עיינו ב-[הפניה לרכיב React](/he/widget/react) לקבלת טבלת המאפיינים המלאה.

לממשק משתמש מותאם אישית לחלוטין, השתמשו ב-[hook ללא ממשק](/he/widget/headless-hook) כדי לנהל את ההפעלה הקולית בזמן שאתם בונים ממשק משלכם. ה-hook חושף רמות שמע בזמן אמת לבניית תצוגות חזותיות המגיבות לשמע.

כל שיחה בווידג'ט היא שיחה. היא נספרת במסגרת [מגבלת השיחות המקבילות](/api-reference/introduction#call-limits) של הארגון שלכם (20 שיחות פעילות כברירת מחדל, המשותפות לשיחות טלפון ולשיחות אחרות) ובמסגרת תקרת הווידג'ט של 25 הפעלות פעילות (או מגבלת השיחות המקבילות שלכם, אם היא גבוהה יותר). בהגעה לכל אחת מהמגבלות, לא ניתן להתחיל שיחה חדשה עד לסיום שיחה קיימת.

---

## אפשרויות שילוב

בחרו את שיטת השילוב המתאימה למערך שלכם:

<CardGroup cols={3}>
  <Card title="רכיב React" icon="react" href="/he/widget/react">
    רכיב ממשק משתמש מוכן מראש עם בקרות שיחה מובנות ותצוגת סטטוס. ייבאו, העבירו מאפיינים, וסיימתם.
  </Card>
  <Card title="Hook ללא ממשק" icon="code" href="/he/widget/headless-hook">
    שליטה מלאה בממשק המשתמש. ה-Hook `useThunderPhone` מנהל את סשן הקול בזמן שאתם בונים ממשק משלכם.
  </Card>
  <Card title="CDN / תגית Script" icon="globe" href="/he/widget/cdn-script-tag">
    אין צורך ב-bundler. טענו את הווידג'ט באמצעות תגית script עבור אתרים סטטיים, WordPress וסביבות אחרות שאינן React.
  </Card>
</CardGroup>

---

## עיצוב

הווידג'ט כולל ערכות נושא בהירות וכהות מובנות, הנשלטות באמצעות המאפיין `theme`, וצבע הדגשה הנשלט באמצעות המאפיין `primaryColor`. להתאמה אישית מעמיקה יותר, תוכלו לדרוס מאפיינים מותאמים אישית ומחלקות CSS. לפרטים, עיינו ב[מדריך העיצוב](/he/widget/styling).

<Note>
  זקוקים לעזרה? צרו איתנו קשר בכתובת [support@thunderphone.com](mailto:support@thunderphone.com)
</Note>