---
title: "Upotettava puhewidget"
description: "Lisää puheagentti mille tahansa verkkosivustolle muutamalla koodirivillä"
---

ThunderPhonen upotettavan puhewidgetin avulla verkkosivustosi kävijät voivat puhua tekoälyagentin kanssa suoraan selaimesta. Puhelua ei tarvita -- käyttäjät napsauttavat painiketta ja aloittavat ThunderPhonen reaaliaikaisen puhekeskustelun.

Widget näkyy lasimaisena palkkina, joka mukautuu vaaleisiin ja tummiin teemoihin. Korostusvärejä ja sijaintia voi mukauttaa. Se jaetaan `@thunderphone/widget`-npm-pakettina, ja se on saatavilla myös CDN:n kautta ympäristöihin, joissa ei käytetä bundleria.

<Frame>
  <img src="/images/widget-showcase.png" alt="ThunderPhone widget in light and dark themes with various accent colors" />
</Frame>

## Vaatimukset

Ennen kuin upotat widgetin, suorita nämä kolme vaihetta [ThunderPhone Dashboardissa](https://app.thunderphone.com):

<Steps>
<Step title="Luo web-widget">
  Siirry hallintapaneelin kohtaan **Web Widgets** ja luo widget. Valitse puheagentti, jonka haluat tuoda näkyviin. Jokaisella widgetillä on oma julkaistava avain (`pk_live_...`), joka on turvallista sisällyttää asiakaspuolen koodiin; agentti määritetään avaimen perusteella.
</Step>

<Step title="Määritä sallitut verkkotunnukset">
  Lisää samaan widgetiin verkkotunnukset, joihin se upotetaan. Jokerimerkit ovat tuettuja (esim. `*.example.com`). Luettelo estää widgetin toiminnan, jos joku kopioi avaimesi toiselle sivustolle; se ei ole todennus, koska selaimen ulkopuolinen skripti voi lähettää minkä tahansa `Origin`-otsakkeen. `localhost` ei ole automaattisesti sallittu tuotannossa: lisää se luetteloon testataksesi paikallisesti tuotanto-APIa vasten.
</Step>

<Step title="Valitse selaimen ohitukset">
  Jos sivusi määrittää `language`, `voice` tai `context`, ota kukin käyttöön kohdassa **Browser overrides**. Uudet widgetit eivät hyväksy mitään, ja istuntopyyntö, joka sisältää käytöstä poistetun asetuksen, epäonnistuu virheellä `400 override_not_allowed`. Katso [Browser overrides](/fi/guides/embed-web-widget).
</Step>
</Steps>

<Warning>
  Julkaistavat avaimet (`pk_live_...`) eivät ole samoja kuin salaiset API-tunnuksesi. Julkaistavat avaimet on suunniteltu asiakaspuolen käyttöön, ja ne on rajattu widget-istuntoihin sallituissa verkkotunnuksissasi. Älä koskaan käytä salaista API-tunnustasi asiakaspuolen koodissa.
</Warning>

<Note>
  Widget-istunnot päättyvät oletusarvoisesti 30 minuutin kuluttua tai aiemmin, jos agentin oma puhelun enimmäiskesto on lyhyempi. Muuta avainkohtaista rajaa [julkaistavassa avaimessa](/api-reference/publishable-keys) asetuksella `max_call_duration_seconds` (enintään 6 tuntia) tai aseta sen arvoksi `null`, jos haluat käyttää agentin omaa rajaa.
</Note>

---

## Pika-aloitus

Asenna paketti:

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

Lisää widget sovellukseesi:

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

Siinä kaikki. Käyttäjäsi näkevät lasimaisen puhelupalkin, joka yhdistää heidät tekoälyagenttiisi yhdellä napsautuksella.

---

## Mukauttaminen

Widgetissä on neljä ulkoasuun liittyvää proppia:

| Proppi | Oletus | Kuvaus |
|------|---------|-------------|
| `theme` | `'light'` | `'light'` valkoiselle lasille, `'dark'` tummalle lasille |
| `primaryColor` | `'#000000'` (vaalea) / `'#ffffff'` (tumma) | Korostusväri aloituspainikkeelle, aaltomuodolle ja yhdistymisen ilmaisimelle |
| `title` | `'Voice assistant'` | Widgetissä näytettävä teksti |
| `position` | `'bottom-right'` | Näkymän kulma: `'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>

Kolme muuta prop-arvoa mukauttaa istuntoa ulkoasun sijaan -- kaikki välitetään istuntopyyntöön puhelun alkaessa. Kukin toimii vain, jos widgetin julkaistava avain sallii sen kohdassa **Selaimen ohitukset**; muussa tapauksessa istuntopyyntö epäonnistuu virheellä `400 override_not_allowed`:

| Proppi | Kuvaus |
|------|-------------|
| `language` | Istuntokohtainen kieliohitus -- koodi tai aluekohtainen tunniste, kuten `en`, `es` tai `fr-FR` |
| `voice` | Istuntokohtainen äänen ohitus -- äänen nimi, kuten `maria` |
| `context` | Agentille välitettävä sivun tai sivuston asiayhteys (katkaistaan palvelinpuolella 12 000 merkkiin) |

Katso täydellinen proppitaulukko [React-komponentin viitteestä](/fi/widget/react).

Täysin mukautettua käyttöliittymää varten käytä [headless-hookia](/fi/widget/headless-hook) puheistunnon hallintaan samalla, kun rakennat oman käyttöliittymäsi. Hook tarjoaa reaaliaikaiset äänitasot äänireaktiivisten visualisointien rakentamiseen.

Jokainen widget-keskustelu on puhelu. Se lasketaan mukaan organisaatiosi [samanaikaisten puhelujen rajaan](/api-reference/introduction#call-limits) (oletusarvoisesti 20 käynnissä olevaa puhelua, jaettu puhelin- ja muiden puhelujen kanssa) sekä widgetin 25 aktiivisen istunnon enimmäismäärään (tai samanaikaisten puhelujen rajaasi, jos se on suurempi). Kummankin rajan kohdalla uutta keskustelua ei voi aloittaa, ennen kuin puhelu päättyy.

---

## Integrointivaihtoehdot

Valitse teknologiaasi sopiva integrointitapa:

<CardGroup cols={3}>
  <Card title="React-komponentti" icon="react" href="/fi/widget/react">
    Valmis käyttöliittymäkomponentti, jossa on sisäänrakennetut puhelunhallinta- ja tilanäyttötoiminnot. Tuo, välitä propsit, valmista.
  </Card>
  <Card title="Headless-hook" icon="code" href="/fi/widget/headless-hook">
    Täysi hallinta käyttöliittymästä. `useThunderPhone`-hook hallitsee puheistuntoa samalla, kun rakennat oman käyttöliittymäsi.
  </Card>
  <Card title="CDN / Script-tagi" icon="globe" href="/fi/widget/cdn-script-tag">
    Ei vaadi bundleria. Lataa widget script-tagilla staattisille sivustoille, WordPressiin ja muihin kuin React-ympäristöihin.
  </Card>
</CardGroup>

---

## Tyylittely

Widgetissä on sisäänrakennetut vaalea ja tumma teema, joita hallitaan `theme`-propilla, sekä korostusväri, jota hallitaan `primaryColor`-propilla. Jos tarvitset laajempaa mukautusta, voit ylikirjoittaa CSS-mukautettuja ominaisuuksia ja luokkia. Lisätietoja on [tyylittelyoppaassa](/fi/widget/styling).

<Note>
  Tarvitsetko apua? Ota yhteyttä: [support@thunderphone.com](mailto:support@thunderphone.com)
</Note>