---
title: "Integrați widgetul web"
description: "Adăugați un agent vocal pe site-ul dumneavoastră de marketing sau de asistență cu un singur tag de script — vizitatorii vorbesc cu acesta direct din browser, fără a fi necesar un număr de telefon."
---

Widgetul web le oferă vizitatorilor site-ului dumneavoastră o conversație prin clic pentru a vorbi
cu un agent vocal cu IA, folosind microfonul browserului. Este un SDK
JavaScript / React separat, cu propria [referință SDK](/ro/widget/overview)
— acest ghid se concentrează pe configurarea din ThunderPhone necesară widgetului.

<Note>
  Puteți face toate acestea fără cURL: pagina din tabloul de bord **Widgeturi web**
  (`/dashboard/web-widgets`) creează widgetul, îi setează modul
  și agentul, gestionează domeniile permise și vă oferă fragmentul de încorporare.
</Note>

## Cerințe preliminare

<Steps>
  <Step title="Creați un agent">
    Agentul al cărui prompt și a cărui voce vor rula sesiunea widgetului. Setați
    `widget_enabled: true` (valoarea implicită).
  </Step>
  <Step title="Decideți modul de rutare">
    - `mode="agent"` — un agent static per cheie. Cea mai simplă opțiune.
    - `mode="webhook"` — serverul dumneavoastră alege agentul pentru fiecare vizitator printr-un
      [webhook `web.incoming`](/ro/webhooks/call-incoming). Utilizați această opțiune pentru
      utilizatori autentificați, teste A/B sau rutare per pagină.
  </Step>
  <Step title="Enumerați domeniile permise">
    Indicați fiecare nume de gazdă care va încorpora widgetul. Browserele trimit
    originea paginii cu fiecare solicitare de sesiune, astfel încât lista împiedică cheia dumneavoastră
    să funcționeze când cineva o copiază pe alt site. Aceasta nu este
    autentificare: un script din afara unui browser poate trimite orice antet
    `Origin`. `localhost` nu este permis automat în producție; pentru a
    testa local cu API-ul de producție, adăugați `localhost` în listă.
  </Step>
  <Step title="Alegeți suprascrierile din browser">
    Decideți ce setări de sesiune poate trimite pagina dumneavoastră. Cheile noi nu acceptă
    niciuna; consultați [Suprascrieri din browser](#browser-overrides).
  </Step>
</Steps>

## Creați o cheie publicabilă

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

Răspunsul include o `key` care începe cu `pk_live_...`. **Cheile publicabile
sunt publice prin concepție** — pot fi incluse în siguranță în pachetul front-end.
Consultați [referința cheilor publicabile](/api-reference/publishable-keys) pentru
toate câmpurile.

<Warning>
  `allowed_domains` trebuie să conțină cel puțin o intrare. `*.example.com`
  corespunde subdomeniilor (de exemplu, `api.example.com`), dar **nu** și
  domeniului fără subdomeniu. Metacaracterele generice simple, precum `*` sau `*.*`, sunt respinse.
</Warning>

## Adăugați widgetul pe site-ul dumneavoastră

Sunt disponibile trei opțiuni de integrare în
[documentația SDK a widgetului](/ro/widget/overview):

<CardGroup cols={3}>
  <Card title="Componentă React" icon="react" href="/ro/widget/react">
    `<ThunderPhoneWidget publishableKey="pk_live_..." />`.
  </Card>
  <Card title="Hook fără interfață" icon="circle-nodes" href="/ro/widget/headless-hook">
    `useThunderPhone()` pentru interfețe personalizate.
  </Card>
  <Card title="Etichetă script CDN" icon="code" href="/ro/widget/cdn-script-tag">
    `ThunderPhone.mount({...})` pentru site-uri fără bundler.
  </Card>
</CardGroup>

Toate cele trei opțiuni acceptă aceeași `publishableKey` și redau butonul de microfon
plus elementul audio din apel.

## Suprascrieri din browser

Widgetul poate trimite patru setări per sesiune din pagină:

| Setare | Proprietate widget | Ce modifică |
|---------|-------------|-----------------|
| `context` | `context` | Text din pagină, adăugat la promptul agentului ca referință |
| `variables` | niciuna (doar `POST /v1/widget/session` brut) | Valori pentru substituenții `{{variable}}` din prompt |
| `voice` | `voice` | Vocea agentului pentru această sesiune |
| `language` | `language` | Limba în care începe sesiunea |

Cheia dvs. publicabilă este publică, astfel încât oricine o are poate trimite aceste
setări, inclusiv dintr-un script care imită domeniul dvs. Prin urmare, fiecare este
dezactivată până când o permiteți pentru cheie: bifați-o la **Suprascrieri din browser**
când creați sau editați widgetul în tabloul de bord ori setați
`allowed_overrides` prin
[API-ul pentru chei publicabile](/api-reference/publishable-keys). Permiteți doar ceea ce
trimite efectiv pagina dvs.

O solicitare de sesiune care include o setare nepermisă de cheie eșuează
cu `400` și o menționează:

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

Verificarea se aplică în ambele moduri. În modul webhook, o setare permisă este
transmisă și către webhookul dumneavoastră `web.incoming` (`context` ajunge ca
`website_context`). Cheile create înainte să existe această setare permit toate
patru, astfel încât integrările existente continuă să funcționeze; dezactivați ce nu utilizați.

`context` al widgetului este trunchiat la 12.000 de caractere (aproximativ 3.400
de tokenuri de text englezesc obișnuit) și este luat în calcul pentru
[suplimentul pentru dimensiunea promptului](/ro/guides/billing-and-topups).
Agentului i se spune să îl trateze ca pe conținutul paginii, nu ca pe instrucțiuni.

## Webhookuri pentru modul widget

Când `mode="webhook"`, ThunderPhone apelează `webhook_url` la fiecare
început de sesiune cu un payload `web.incoming`. Returnați configurația
agentului pe care doriți să îl rulați pentru acel vizitator — aceasta urmează aceeași
[schemă de răspuns](/ro/webhooks/call-incoming) ca apelurile
telefonice:

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

Puteți combina în instrucțiuni contextul din propria sesiune (ce client navighează,
pe ce pagină se află) și puteți schimba agenții pentru fiecare lansare graduală.

## Monitorizați sesiunile

Sesiunile widget apar în
[`GET /v1/calls`](/api-reference/calls#list-calls) cu
`direction="widget"` — aceeași transcriere, înregistrare, evaluare și
facturare ca apelurile telefonice. Filtrați după `direction` pentru a crea un
tablou de bord doar pentru widget.

---

## Pașii următori

<CardGroup cols={2}>
  <Card title="Referință SDK pentru widget" icon="window-maximize" href="/ro/widget/overview">
    Detalii de integrare React / hook / CDN.
  </Card>
  <Card title="Configurație dinamică per apel" icon="bolt" href="/ro/guides/dynamic-call-config">
    Implementați fluxul `mode="webhook"` de la început până la final.
  </Card>
  <Card title="Referință pentru chei publicabile" icon="key" href="/api-reference/publishable-keys">
    Fiecare câmp al resursei cheii.
  </Card>
  <Card title="API pentru sesiuni cu microfon" icon="microphone" href="/api-reference/mic-sessions">
    Omiteți widgetul; controlați LiveKit direct pentru interfețe personalizate.
  </Card>
</CardGroup>