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

# Componentă React

> Integrați widgetul vocal ThunderPhone într-o aplicație React

Componenta `ThunderPhoneWidget` redă o bară de apel cu aspect glassmorphic, cu controale integrate pentru dezactivarea sunetului, încheierea apelului și afișarea stării conexiunii. Este cea mai rapidă modalitate de a adăuga AI vocal într-o aplicație React.

## Instalare

```bash theme={null}
npm install @thunderphone/widget
```

## Utilizare de bază

```tsx theme={null}
import { ThunderPhoneWidget } from '@thunderphone/widget'
import '@thunderphone/widget/style.css'

function App() {
  return (
    <ThunderPhoneWidget
      publishableKey="pk_live_your_publishable_key"
    />
  )
}
```

<Warning>
  Trebuie să importați fișierul CSS pentru ca widgetul să fie redat corect. Fără acesta, widgetul nu va avea stilizare.
</Warning>

***

## Proprietăți

Componenta acceptă următoarele proprietăți prin `ThunderPhoneWidgetProps`:

| Proprietate      | Tip                                                            | Obligatoriu | Implicit                                     | Descriere                                                                                                                                                                                                               |
| ---------------- | -------------------------------------------------------------- | ----------- | -------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `publishableKey` | `string`                                                       | Da          | --                                           | Cheie API publicabilă (`pk_live_...`) din setările Dezvoltatori. Agentul este determinat automat din configurația widgetului asociată cheii.                                                                            |
| `theme`          | `'light' \| 'dark'`                                            | Nu          | `'light'`                                    | Schemă de culori. Aplică clasa `tp--light` sau `tp--dark` la rădăcina widgetului.                                                                                                                                       |
| `primaryColor`   | `string`                                                       | Nu          | `'#000000'` (deschis) / `'#ffffff'` (închis) | Șir de culoare CSS utilizat ca culoare de accent (butonul de apel, forma de undă, indicatorii activi).                                                                                                                  |
| `title`          | `string`                                                       | Nu          | `'Voice assistant'`                          | Text afișat în bara widgetului.                                                                                                                                                                                         |
| `position`       | `'bottom-right' \| 'bottom-left' \| 'top-right' \| 'top-left'` | Nu          | `'bottom-right'`                             | Poziție fixă în fereastra de vizualizare pentru widget.                                                                                                                                                                 |
| `apiBase`        | `string`                                                       | Nu          | `'https://api.thunderphone.com/v1'`          | Suprascriere pentru URL-ul de bază al API-ului.                                                                                                                                                                         |
| `language`       | `string`                                                       | Nu          | --                                           | Suprascrierea limbii pentru fiecare sesiune -- un cod de limbă sau o setare regională, precum `en`, `es` sau `fr-FR`. Dacă nu este setată, se aplică limba configurată a agentului.                                     |
| `voice`          | `string`                                                       | Nu          | --                                           | Suprascrierea vocii pentru fiecare sesiune -- un nume de voce, precum `maria`. Dacă nu este setată, se aplică vocea configurată a agentului.                                                                            |
| `context`        | `string`                                                       | Nu          | --                                           | Context factual al paginii sau site-ului, pentru fiecare sesiune, transmis agentului (de exemplu, detalii despre pagina pe care o vizualizează vizitatorul). Este trunchiat pe partea de server la 12.000 de caractere. |
| `onConnect`      | `() => void`                                                   | Nu          | --                                           | Apelată când sesiunea vocală se conectează cu succes.                                                                                                                                                                   |
| `onDisconnect`   | `() => void`                                                   | Nu          | --                                           | Apelată când sesiunea se încheie.                                                                                                                                                                                       |
| `onError`        | `(error) => void`                                              | Nu          | --                                           | Apelată la apariția erorilor. Obiectul `error` are câmpurile `error` (cod) și `message`.                                                                                                                                |
| `className`      | `string`                                                       | Nu          | --                                           | Nume de clasă CSS suplimentar aplicat containerului widgetului.                                                                                                                                                         |
| `ringtone`       | `boolean \| string`                                            | Nu          | `false`                                      | Redați un ton de apel în timpul conectării. `true` pentru tonul de apel implicit sau un șir URL pentru audio personalizat.                                                                                              |

***

## Exemple

### Temă întunecată cu culoare personalizată

```tsx theme={null}
import { ThunderPhoneWidget } from '@thunderphone/widget'
import '@thunderphone/widget/style.css'

function App() {
  return (
    <ThunderPhoneWidget
      publishableKey="pk_live_your_publishable_key"
      theme="dark"
      primaryColor="#8b5cf6"
      title="Talk to our AI"
    />
  )
}
```

### Poziție personalizată

```tsx theme={null}
import { ThunderPhoneWidget } from '@thunderphone/widget'
import '@thunderphone/widget/style.css'

function App() {
  return (
    <ThunderPhoneWidget
      publishableKey="pk_live_your_publishable_key"
      position="bottom-left"
    />
  )
}
```

### Limbă, voce și context pentru fiecare sesiune

Proprietățile `language`, `voice` și `context` sunt transmise cererii de sesiune (`POST /widget/session`) la inițierea unui apel, înlocuind valorile implicite configurate pentru agent pentru sesiunea respectivă:

```tsx theme={null}
import { ThunderPhoneWidget } from '@thunderphone/widget'
import '@thunderphone/widget/style.css'

function PricingPageWidget() {
  return (
    <ThunderPhoneWidget
      publishableKey="pk_live_your_publishable_key"
      language="es"
      voice="maria"
      context="Page: Pricing. Plans: Starter $29/mo, Pro $99/mo. Annual billing saves 20%."
    />
  )
}
```

Utilizați `context` pentru a oferi agentului informații factuale despre pagina pe care se află vizitatorul -- detalii despre produs, prețuri sau întrebări frecvente specifice paginii. Acesta este trunchiat pe server la 12.000 de caractere.

### Cu callback-uri pentru evenimente

```tsx theme={null}
import { ThunderPhoneWidget } from '@thunderphone/widget'
import '@thunderphone/widget/style.css'

function SupportWidget() {
  return (
    <ThunderPhoneWidget
      publishableKey="pk_live_your_publishable_key"
      onConnect={() => {
        console.log('Voice session connected')
        analytics.track('widget_call_started')
      }}
      onDisconnect={() => {
        console.log('Voice session ended')
        analytics.track('widget_call_ended')
      }}
      onError={(error) => {
        console.error(`Widget error: ${error.error} - ${error.message}`)
      }}
    />
  )
}
```

### Cu stilizare personalizată

```tsx theme={null}
import { ThunderPhoneWidget } from '@thunderphone/widget'
import '@thunderphone/widget/style.css'

function BrandedWidget() {
  return (
    <ThunderPhoneWidget
      publishableKey="pk_live_your_publishable_key"
      primaryColor="#4a90d9"
      className="my-custom-widget"
    />
  )
}
```

```css theme={null}
.my-custom-widget .tp-button--end {
  background-color: #e74c3c;
}
```

Consultați [ghidul de stilizare](/ro/widget/styling) pentru toate clasele CSS și proprietățile personalizate disponibile.

### Cu ton de apel

Redați un sunet de telefon care sună în timp ce se stabilește conexiunea:

```tsx theme={null}
import { ThunderPhoneWidget } from '@thunderphone/widget'
import '@thunderphone/widget/style.css'

function PhoneWidget() {
  return (
    <ThunderPhoneWidget
      publishableKey="pk_live_your_publishable_key"
      ringtone={true}
    />
  )
}
```

Utilizați un ton de apel personalizat transmițând un URL către un fișier audio:

```tsx theme={null}
<ThunderPhoneWidget
  publishableKey="pk_live_your_publishable_key"
  ringtone="https://example.com/my-ringtone.mp3"
/>
```

Tonul de apel se repetă cât timp widgetul este în starea `connecting` și se estompează treptat atunci când agentul se conectează.

### Cu bază API personalizată

<Tip>
  Trebuie să setați `apiBase` doar dacă utilizați un endpoint API autogăzduit sau proxy. Valoarea implicită indică spre `https://api.thunderphone.com/v1`.
</Tip>

```tsx theme={null}
<ThunderPhoneWidget
  publishableKey="pk_live_your_publishable_key"
  apiBase="https://your-proxy.example.com/v1"
/>
```

***

## Gestionarea erorilor

Când este declanșat callback-ul `onError`, acesta primește un obiect de eroare cu două câmpuri:

| Câmp      | Tip      | Descriere                                              |
| --------- | -------- | ------------------------------------------------------ |
| `error`   | `string` | Cod de eroare care poate fi citit de mașină            |
| `message` | `string` | Descriere de eroare care poate fi citită de utilizator |

Codurile de eroare frecvente includ domeniu nepermis, agent negăsit și cheie API nevalidă.

***

## Pașii următori

<CardGroup cols={2}>
  <Card title="Hook headless" icon="code" href="/ro/widget/headless-hook">
    Aveți nevoie de control complet asupra interfeței? Folosiți în schimb hook-ul `useThunderPhone`.
  </Card>

  <Card title="Stilizare" icon="palette" href="/ro/widget/styling">
    Personalizați culorile, dimensiunile și aspectul cu proprietăți personalizate CSS.
  </Card>
</CardGroup>