> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thunderphone.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Upota verkkowidget

> Lisää puheagentti markkinointi- tai tukisivustollesi — puhelinnumeroa ei tarvita.

Web-widget tarjoaa sivustosi kävijöille klikkaa ja puhu -keskustelun
tekoälyagentin kanssa selaimen mikrofonia käyttäen. Se on erillinen
JavaScript- / React SDK, jolla on oma [SDK-viite](/fi/widget/overview)
— tämä opas keskittyy widgetin tarvitsemiin ThunderPhone-puolen asetuksiin.

<Note>
  Voit tehdä kaiken tämän ilman cURL:ia: hallintapaneelin **Web-widgetit**-sivu
  (`/dashboard/web-widgets`) luo widgetin, määrittää sen tilan
  ja agentin, hallitsee sallittuja verkkotunnuksia ja antaa sinulle upotuskoodin.
</Note>

## Vaatimukset

<Steps>
  <Step title="Luo agentti">
    Agentti, jonka kehote ja ääni suorittavat widget-istunnon. Määritä
    `widget_enabled: true` (oletusarvo).
  </Step>

  <Step title="Valitse reititystapa">
    * `mode="agent"` — yksi staattinen agentti avainta kohden. Yksinkertaisin vaihtoehto.
    * `mode="webhook"` — palvelimesi valitsee agentin kävijäkohtaisesti
      [`web.incoming`-webhookin](/fi/webhooks/call-incoming) kautta. Käytä tätä
      kirjautuneille käyttäjille, A/B-testeihin tai sivukohtaiseen reititykseen.
  </Step>

  <Step title="Luettele sallitut verkkotunnukset">
    Julkaistavat avaimet on sidottu alkuperään. Sinun on nimettävä jokainen isäntänimi,
    johon widget upotetaan. `localhost` / `127.0.0.1` ovat aina
    sallittuja paikallisen kehityksen aikana.
  </Step>
</Steps>

## Luo julkaistava avain

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

  ```bash Dynamic via webhook theme={null}
  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>

Vastaus sisältää `key`-arvon, joka alkaa merkkijonolla `pk_live_...`. **Julkaistavat
avaimet ovat tarkoituksella julkisia** — ne on turvallista sisällyttää käyttöliittymäpakettiisi.
Katso kaikki kentät [julkaistavien avainten viitteestä](/api-reference/publishable-keys).

<Warning>
  `allowed_domains`-kentässä on oltava vähintään yksi merkintä. `*.example.com`
  vastaa aliverkkotunnuksia (esim. `api.example.com`), mutta **ei** pelkkää
  verkkotunnusta. Paljaat jokerimerkit, kuten `*` tai `*.*`, hylätään.
</Warning>

## Lisää widget sivustollesi

Kolme integrointivaihtoehtoa käsitellään
[widgetin SDK-dokumentaatiossa](/fi/widget/overview):

<CardGroup cols={3}>
  <Card title="React-komponentti" icon="react" href="/fi/widget/react">
    `<ThunderPhoneWidget publishableKey="pk_live_..." />`.
  </Card>

  <Card title="Headless-hook" icon="circle-nodes" href="/fi/widget/headless-hook">
    `useThunderPhone()` mukautettuja käyttöliittymiä varten.
  </Card>

  <Card title="CDN-skriptitagi" icon="code" href="/fi/widget/cdn-script-tag">
    `ThunderPhone.mount({...})` sivustoille ilman paketoijaa.
  </Card>
</CardGroup>

Kaikki kolme hyväksyvät saman `publishableKey`-arvon ja renderöivät mikrofonipainikkeen
sekä puhelun aikaisen äänielementin.

Widgetin `context` katkaistaan 12 000 merkkiin (noin 3 400 tokenia
tyypillisessä englanninkielisessä tekstissä), ja se otetaan huomioon
[kehotekoon lisämaksussa](/fi/guides/billing-and-topups).

## Widget-tilan webhookit

Kun `mode="webhook"`, ThunderPhone kutsuu `webhook_url`-osoitettasi jokaisen
istunnon alkaessa `web.incoming`-payloadilla. Palauta agenttimääritys,
jota haluat käyttää kyseiselle kävijälle — se noudattaa samaa
[vastausskeemaa](/fi/webhooks/call-incoming) kuin puhelut:

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

Voit lisätä kehotteeseen oman istuntosi kontekstia (mitä asiakasta käyttäjä selaa,
millä sivulla hän on) ja vaihtaa agentteja käyttöönoton mukaan.

## Tarkastele istuntoja

Widget-istunnot näkyvät kohteessa
[`GET /v1/calls`](/api-reference/calls#list-calls) arvolla
`direction="widget"` — niissä ovat samat litteroinnit, tallenteet, arvioinnit ja
laskutus kuin puheluissa. Suodata `direction`-kentän mukaan rakentaaksesi vain widgetejä koskevan
hallintapaneelin.

***

## Seuraavat vaiheet

<CardGroup cols={2}>
  <Card title="Widget SDK -viite" icon="window-maximize" href="/fi/widget/overview">
    React-, hook- ja CDN-integraation tiedot.
  </Card>

  <Card title="Dynaaminen puhelukohtainen määritys" icon="bolt" href="/fi/guides/dynamic-call-config">
    Toteuta `mode="webhook"`-työnkulku alusta loppuun.
  </Card>

  <Card title="Julkaistavien avainten viite" icon="key" href="/api-reference/publishable-keys">
    Kaikki avainresurssin kentät.
  </Card>

  <Card title="Mikrofonistuntojen API" icon="microphone" href="/api-reference/mic-sessions">
    Ohita widget; ohjaa LiveKit-palvelua suoraan mukautettuja käyttöliittymiä varten.
  </Card>
</CardGroup>