---
title: "Webes widget beágyazása"
description: "Egyetlen scriptcímkével helyezzen el hangalapú AI-ügynököt marketing- vagy támogatási webhelyén — a látogatók közvetlenül a böngészőből beszélhetnek vele, telefonszám nélkül."
---

A webes widget lehetővé teszi, hogy a webhely látogatói a böngésző mikrofonját használva, kattintással indítsanak beszélgetést egy AI-ügynökkel. Ez egy különálló JavaScript / React SDK saját [SDK-referenciával](/hu/widget/overview) — ez az útmutató a widgethez szükséges ThunderPhone-oldali beállításokra összpontosít.

<Note>
  Mindezt cURL nélkül is elvégezheti: a **Webes widgetek** irányítópultoldal
  (`/dashboard/web-widgets`) létrehozza a widgetet, beállítja annak módját
  és ügynökét, kezeli az engedélyezett domaineket, és átadja a beágyazási kódrészletet.
</Note>

## Előfeltételek

<Steps>
  <Step title="AI-ügynök létrehozása">
    Az az AI-ügynök, amelynek promptja és hangja futtatja a widgetmunkamenetet. Állítsa be a
    `widget_enabled: true` értéket (ez az alapértelmezett).
  </Step>
  <Step title="Az útválasztási mód kiválasztása">
    - `mode="agent"` — kulcsonként egy statikus AI-ügynök. A legegyszerűbb.
    - `mode="webhook"` — a szervere látogatónként választja ki az AI-ügynököt egy
      [`web.incoming` webhook](/hu/webhooks/call-incoming) segítségével. Használja ezt
      bejelentkezett felhasználókhoz, A/B-tesztekhez vagy oldalankénti útválasztáshoz.
  </Step>
  <Step title="Az engedélyezett domainek felsorolása">
    Adjon meg minden gazdagépnevet, amely beágyazza a widgetet. A böngészők minden
    munkamenet-kéréssel elküldik az oldal eredetét, így a lista megakadályozza, hogy a kulcsa
    működjön, ha valaki átmásolja egy másik webhelyre. Ez nem hitelesítés: a böngészőn kívüli
    szkript bármilyen `Origin` fejlécet küldhet. A `localhost` éles környezetben nem engedélyezett
    automatikusan; ha helyileg szeretne tesztelni az éles API-val, adja hozzá a `localhost` értéket
    a listához.
  </Step>
  <Step title="A böngészőbeli felülbírálások kiválasztása">
    Döntse el, mely munkamenet-beállításokat küldheti az oldala. Az új kulcsok egyiket sem
    engedélyezik; lásd: [Böngészőbeli felülbírálások](#browser-overrides).
  </Step>
</Steps>

## Publikálható kulcs létrehozása

<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>

A válasz egy `pk_live_...` kezdetű `key` értéket tartalmaz. **A publikálható
kulcsok kialakításukból adódóan nyilvánosak** — biztonságosan elhelyezhetők a front-end
csomagban. Az összes mezőért lásd a [Publikálható kulcsok referenciáját](/api-reference/publishable-keys).

<Warning>
  Az `allowed_domains` mezőnek legalább egy bejegyzést kell tartalmaznia. A `*.example.com`
  megfelel az aldomaineknek (például `api.example.com`), de **nem** az
  csupasz domainnek. Az olyan csupasz helyettesítő karakterek, mint a `*` vagy a `*.*`, elutasításra kerülnek.
</Warning>

## Helyezze el a widgetet a webhelyén

Három integrációs lehetőséget ismertet a
[widget SDK dokumentációja](/hu/widget/overview):

<CardGroup cols={3}>
  <Card title="React-komponens" icon="react" href="/hu/widget/react">
    `<ThunderPhoneWidget publishableKey="pk_live_..." />`.
  </Card>
  <Card title="Headless hook" icon="circle-nodes" href="/hu/widget/headless-hook">
    `useThunderPhone()` egyéni felhasználói felületekhez.
  </Card>
  <Card title="CDN-szkriptcímke" icon="code" href="/hu/widget/cdn-script-tag">
    `ThunderPhone.mount({...})` csomagoló nélküli webhelyekhez.
  </Card>
</CardGroup>

Mindhárom ugyanazt a `publishableKey` értéket fogadja el, és megjeleníti a mikrofon gombját,
valamint a hívás közbeni hangelemet.

## Böngészőbeli felülbírálások

A widget munkamenetenként négy beállítást küldhet az oldalról:

| Beállítás | Widgetprop | Mit módosít |
|---------|-------------|-----------------|
| `context` | `context` | Az oldal szövege, referenciaként hozzáfűzve az ügynök promptjához |
| `variables` | nincs (csak nyers `POST /v1/widget/session`) | A promptban lévő `{{variable}}` helyőrzők értékei |
| `voice` | `voice` | Az ügynök hangja ebben a munkamenetben |
| `language` | `language` | Az a nyelv, amelyen a munkamenet elindul |

A publikálható kulcsa nyilvános, ezért bárki, aki rendelkezik vele, elküldheti ezeket a
beállításokat, akár az Ön domainjét meghamisító szkriptből is. Ezért mindegyik alapértelmezés szerint
ki van kapcsolva, amíg nem engedélyezi az adott kulcsnál: a vezérlőpulton a widget létrehozásakor
vagy szerkesztésekor jelölje be a **Böngészőfelülbírálások** alatt, vagy állítsa be az
`allowed_overrides` értékét a
[Publikálható kulcsok API](/api-reference/publishable-keys) segítségével. Csak azt
engedélyezze, amit az oldala ténylegesen elküld.

Ha egy munkamenet-kérés olyan beállítást tartalmaz, amelyet a kulcs nem engedélyez, a kérés
`400` hibával meghiúsul, és megnevezi azt:

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

Az ellenőrzés mindkét módban érvényes. Webhook módban az engedélyezett beállítás
a `web.incoming` webhookhoz is továbbításra kerül (`context` értéke
`website_context` néven érkezik). A beállítás bevezetése előtt létrehozott kulcsok
mind a négyet engedélyezik, így a meglévő beágyazások továbbra is működnek; kapcsolja ki azt,
amit nem használ.

A widget `context` értéke 12 000 karakterre csonkolódik (ez nagyjából 3 400
tokennyi tipikus angol szöveg), és beleszámít a
[promptméret-felárba](/hu/guides/billing-and-topups).
Az ügynök azt az utasítást kapja, hogy oldaltartalomként, ne utasításként kezelje.

## Widget módú webhookok

`mode="webhook"` esetén a ThunderPhone minden munkamenet indításakor meghívja az Ön
`webhook_url` címét egy `web.incoming` adattartalommal. Adja vissza az adott látogatóhoz
futtatni kívánt ügynökkonfigurációt — ez ugyanazt a
[válaszsémát](/hu/webhooks/call-incoming) követi, mint a telefonhívások:

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

A saját munkamenetéből származó kontextust (melyik ügyfél böngészik,
melyik oldalon van) beillesztheti a promptba, és bevezetésenként cserélheti az ügynököket.

## Munkamenetek megfigyelése

A widgetmunkamenetek a
[`GET /v1/calls`](/api-reference/calls#list-calls) végpontban jelennek meg
`direction="widget"` értékkel — ugyanazzal az átirattal, felvétellel, értékeléssel és
számlázással, mint a telefonhívások esetében. Szűrjön a `direction` alapján, hogy csak widgetes
irányítópultot hozzon létre.

---

## Következő lépések

<CardGroup cols={2}>
  <Card title="Widget SDK-referencia" icon="window-maximize" href="/hu/widget/overview">
    A React-, hook- és CDN-integráció részletei.
  </Card>
  <Card title="Dinamikus hívásonkénti konfiguráció" icon="bolt" href="/hu/guides/dynamic-call-config">
    Valósítsa meg a `mode="webhook"` folyamatot teljes körűen.
  </Card>
  <Card title="Publikálható kulcsok referenciája" icon="key" href="/api-reference/publishable-keys">
    A kulcserőforrás minden mezője.
  </Card>
  <Card title="Mikrofonos munkamenetek API-ja" icon="microphone" href="/api-reference/mic-sessions">
    Hagyja ki a widgetet; egyéni felületekhez vezérelje közvetlenül a LiveKitet.
  </Card>
</CardGroup>