---
title: "Beágyazható hangalapú widget"
description: "Adjon hozzá hangalapú AI-ügynököt bármely webhelyhez néhány sor kóddal"
---

A ThunderPhone beágyazható hangwidgetje lehetővé teszi, hogy webhelye látogatói közvetlenül a böngészőből beszéljenek egy AI-ügynökkel. Nincs szükség telefonhívásra -- a felhasználók egy gombra kattintanak, és valós idejű, ThunderPhone által működtetett hangbeszélgetést indítanak.

A widget üvegszerű sávként jelenik meg, amely alkalmazkodik a világos és sötét témákhoz, testreszabható kiemelőszínekkel és pozicionálással. Az `@thunderphone/widget` npm-csomagként érhető el, valamint CDN-en keresztül is használható nem bundlert használó környezetekben.

<Frame>
  <img src="/images/widget-showcase.png" alt="ThunderPhone widget világos és sötét témákban, különböző kiemelőszínekkel" />
</Frame>

## Előfeltételek

A widget beágyazása előtt végezze el ezt a három lépést a [ThunderPhone Dashboardban](https://app.thunderphone.com):

<Steps>
<Step title="Webes widget létrehozása">
  Az irányítópulton lépjen a **Webes widgetek** menübe, és hozzon létre egy widgetet. Válassza ki a közzétenni kívánt ügynököt. Minden widget saját közzétehető kulccsal (`pk_live_...`) rendelkezik, amely biztonságosan szerepeltethető kliensoldali kódban; az ügynök a kulcs alapján kerül meghatározásra.
</Step>

<Step title="Engedélyezett domainek konfigurálása">
  Ugyanazon a widgeten adja hozzá azokat a domaineket, ahol be lesz ágyazva. Helyettesítő karakterek is támogatottak (például: `*.example.com`). A lista megakadályozza, hogy a widget működjön, ha valaki átmásolja a kulcsát egy másik webhelyre; ez nem hitelesítés, mivel egy böngészőn kívüli szkript bármilyen `Origin` fejlécet küldhet. A `localhost` éles környezetben nincs automatikusan engedélyezve: adja hozzá a listához, hogy helyileg tesztelhessen az éles API-val.
</Step>

<Step title="Böngészőbeli felülbírálások kiválasztása">
  Ha oldala beállítja a `language`, `voice` vagy `context` értékét, kapcsolja be mindegyiket a **Böngészőbeli felülbírálások** alatt. Az új widgetek egyiket sem fogadják el, és a kikapcsolt beállítást tartalmazó munkamenet-kérelem `400 override_not_allowed` hibával meghiúsul. Lásd: [Böngészőbeli felülbírálások](/hu/guides/embed-web-widget).
</Step>
</Steps>

<Warning>
  A közzétehető kulcsok (`pk_live_...`) **nem** azonosak a titkos API-tokenjeivel. A közzétehető kulcsok kliensoldali használatra készültek, és az engedélyezett domaineken futó widgetmunkamenetekre vannak korlátozva. Soha ne használja a titkos API-tokenjét kliensoldali kódban.
</Warning>

<Note>
  A widget-munkamenetek alapértelmezés szerint 30 perc után érnek véget, vagy hamarabb, ha az ügynök saját maximális hívásidőtartama rövidebb. Kulcsonként módosítsa a korlátot a [közzétehető kulcson](/api-reference/publishable-keys) található `max_call_duration_seconds` használatával (legfeljebb 6 óráig), vagy állítsa `null` értékre az ügynök saját korlátjának használatához.
</Note>

---

## Gyors kezdés

Telepítse a csomagot:

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

Illessze be a widgetet az alkalmazásába:

```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"
    />
  )
}
```

Ennyi az egész. Felhasználói egy üvegszerű hívássávot látnak, amely egyetlen kattintással összeköti őket az AI-ügynökével.

---

## Testreszabás

A widget négy megjelenési proppal rendelkezik:

| Prop | Alapértelmezett | Leírás |
|------|---------|-------------|
| `theme` | `'light'` | `'light'` fehér üveghez, `'dark'` sötét üveghez |
| `primaryColor` | `'#000000'` (világos) / `'#ffffff'` (sötét) | Kiemelőszín az indítógombhoz, a hullámformához és a kapcsolódási jelzőhöz |
| `title` | `'Voice assistant'` | A widgetben megjelenített szöveg |
| `position` | `'bottom-right'` | A nézetablak sarka: `'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>

Három további prop a munkamenetet szabja testre, nem a megjelenést -- hívás indításakor mindegyik továbbításra kerül a munkamenet-kérelemhez. Mindegyik csak akkor működik, ha a widget publikálható kulcsa ezt engedélyezi a **Böngésző-felülbírálások** alatt; ellenkező esetben a munkamenet-kérelem `400 override_not_allowed` hibával meghiúsul:

| Prop | Leírás |
|------|-------------|
| `language` | Munkamenetenkénti nyelvi felülbírálás -- például `en`, `es` vagy `fr-FR` kód vagy területi beállítás |
| `voice` | Munkamenetenkénti hangfelülbírálás -- például `maria` hangnév |
| `context` | Az ügynöknek átadott tényszerű oldal- vagy webhelykontextus (a szerveroldalon 12 000 karakterre csonkítva) |

A teljes proptáblázatért tekintse meg a [React-komponens referenciáját](/hu/widget/react).

Teljesen egyedi felülethez használja a [headless hookot](/hu/widget/headless-hook) a hangmunkamenet kezeléséhez, miközben saját felületet épít. A hook valós idejű hangszinteket biztosít hangra reagáló vizualizációk készítéséhez.

Minden widgetes beszélgetés egy hívás. Ez beleszámít a szervezet [egyidejű hívásokra vonatkozó korlátjába](/api-reference/introduction#call-limits) (alapértelmezés szerint 20 folyamatban lévő hívás, amely a telefonos és más hívásokkal közös), valamint a widget 25 aktív munkamenetre vonatkozó korlátjába (vagy az egyidejű hívások korlátjába, ha az magasabb). Bármelyik korlát elérésekor új beszélgetés csak egy hívás befejezése után indítható.

---

## Integrációs lehetőségek

Válassza ki a technológiai környezetéhez illő integrációs módszert:

<CardGroup cols={3}>
  <Card title="React-komponens" icon="react" href="/hu/widget/react">
    Előre elkészített felhasználói felületi komponens beépített hívásvezérlőkkel és állapotkijelzéssel. Importálja, adja át a propokat, és kész.
  </Card>
  <Card title="Headless hook" icon="code" href="/hu/widget/headless-hook">
    Teljes kontroll a felhasználói felület felett. A `useThunderPhone` hook kezeli a hangmunkamenetet, miközben Ön saját felületet épít.
  </Card>
  <Card title="CDN / Script tag" icon="globe" href="/hu/widget/cdn-script-tag">
    Nincs szükség bundlerre. Töltse be a widgetet script taggel statikus webhelyekhez, WordPresshez és más, nem React-alapú környezetekhez.
  </Card>
</CardGroup>

---

## Stílus

A widget beépített világos és sötét témákat tartalmaz, amelyeket a `theme` prop vezérel, valamint egy kiemelőszínt, amelyet a `primaryColor` prop szabályoz. Mélyebb testreszabáshoz felülírhatja a CSS egyéni tulajdonságait és osztályait. Részletekért tekintse meg a [stílusútmutatót](/hu/widget/styling).

<Note>
  Segítségre van szüksége? Lépjen kapcsolatba velünk a [support@thunderphone.com](mailto:support@thunderphone.com) címen.
</Note>