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

# React-komponent

> Bädda in ThunderPhones röstwidget i en React-applikation

Komponenten `ThunderPhoneWidget` renderar ett glasliknande samtalsfält med inbyggda kontroller för att stänga av ljudet, avsluta samtalet och visa anslutningsstatus. Det är det snabbaste sättet att lägga till röst-AI i en React-app.

## Installation

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

## Grundläggande användning

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

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

<Warning>
  Du **måste** importera CSS-filen för att widgeten ska renderas korrekt. Utan den saknar widgeten formatering.
</Warning>

***

## Egenskaper

Komponenten accepterar följande egenskaper via `ThunderPhoneWidgetProps`:

| Egenskap         | Typ                                                            | Krävs | Standard                                  | Beskrivning                                                                                                                                                                         |
| ---------------- | -------------------------------------------------------------- | ----- | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `publishableKey` | `string`                                                       | Ja    | --                                        | Publicerbar API-nyckel (`pk_live_...`) från utvecklarinställningarna. Agenten fastställs automatiskt från nyckelns widgetkonfiguration.                                             |
| `theme`          | `'light' \| 'dark'`                                            | Nej   | `'light'`                                 | Färgschema. Tillämpar klassen `tp--light` eller `tp--dark` på widgetens rotelement.                                                                                                 |
| `primaryColor`   | `string`                                                       | Nej   | `'#000000'` (ljust) / `'#ffffff'` (mörkt) | CSS-färgsträng som används som accentfärg (samtalsknapp, vågform, aktiva indikatorer).                                                                                              |
| `title`          | `string`                                                       | Nej   | `'Voice assistant'`                       | Text som visas i widgetfältet.                                                                                                                                                      |
| `position`       | `'bottom-right' \| 'bottom-left' \| 'top-right' \| 'top-left'` | Nej   | `'bottom-right'`                          | Fast position i visningsområdet för widgeten.                                                                                                                                       |
| `apiBase`        | `string`                                                       | Nej   | `'https://api.thunderphone.com/v1'`       | Åsidosättning av API-bas-URL.                                                                                                                                                       |
| `language`       | `string`                                                       | Nej   | --                                        | Åsidosättning av språk per session -- en språkkod eller språkvariant, till exempel `en`, `es` eller `fr-FR`. När den inte är angiven används agentens konfigurerade språk.          |
| `voice`          | `string`                                                       | Nej   | --                                        | Åsidosättning av röst per session -- ett röstnamn som `maria`. När den inte är angiven används agentens konfigurerade röst.                                                         |
| `context`        | `string`                                                       | Nej   | --                                        | Faktabaserad sid- eller webbplatskontext per session som skickas till agenten (till exempel information om sidan som besökaren visar). Trunkeras på serversidan till 12 000 tecken. |
| `onConnect`      | `() => void`                                                   | Nej   | --                                        | Anropas när röstsessionen ansluts.                                                                                                                                                  |
| `onDisconnect`   | `() => void`                                                   | Nej   | --                                        | Anropas när sessionen avslutas.                                                                                                                                                     |
| `onError`        | `(error) => void`                                              | Nej   | --                                        | Anropas vid fel. Objektet `error` har fälten `error` (kod) och `message`.                                                                                                           |
| `className`      | `string`                                                       | Nej   | --                                        | Ytterligare CSS-klassnamn som tillämpas på widgetbehållaren.                                                                                                                        |
| `ringtone`       | `boolean \| string`                                            | Nej   | `false`                                   | Spela en ringsignal medan anslutningen upprättas. `true` för standardringsignalen eller en URL-sträng för anpassat ljud.                                                            |

***

## Exempel

### Mörkt tema med anpassad färg

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

### Anpassad position

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

### Språk, röst och kontext per session

Propparna `language`, `voice` och `context` skickas vidare till sessionsbegäran (`POST /widget/session`) när ett samtal startar och åsidosätter agentens konfigurerade standardvärden för den sessionen:

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

Använd `context` för att ge agenten faktakunskap om sidan som besökaren är på – produktinformation, priser eller vanliga frågor som är specifika för sidan. Den trunkeras på serversidan till 12 000 tecken.

### Med händelseåteranrop

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

### Med anpassad stil

```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;
}
```

Se [stilguiden](/sv/widget/styling) för alla tillgängliga CSS-klasser och anpassade egenskaper.

### Med ringsignal

Spela upp ett telefonringsignal medan anslutningen upprättas:

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

Använd en anpassad ringsignal genom att ange en URL till en ljudfil:

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

Ringsignalen upprepas medan widgeten är i tillståndet `connecting` och tonas ut mjukt när agenten ansluter.

### Med anpassad API-bas

<Tip>
  Du behöver bara ange `apiBase` om du använder en egenhostad eller proxybaserad API-slutpunkt. Standardvärdet pekar på `https://api.thunderphone.com/v1`.
</Tip>

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

***

## Felhantering

När återanropet `onError` utlöses får det ett felobjekt med två fält:

| Fält      | Typ      | Beskrivning                   |
| --------- | -------- | ----------------------------- |
| `error`   | `string` | Maskinläsbar felkod           |
| `message` | `string` | Människoläsbar felbeskrivning |

Vanliga felkoder omfattar domän ej tillåten, agent hittades inte och ogiltig API-nyckel.

***

## Nästa steg

<CardGroup cols={2}>
  <Card title="Headless-hook" icon="code" href="/sv/widget/headless-hook">
    Behöver du full kontroll över användargränssnittet? Använd hooken `useThunderPhone` i stället.
  </Card>

  <Card title="Stilsättning" icon="palette" href="/sv/widget/styling">
    Anpassa färger, storlekar och layout med anpassade CSS-egenskaper.
  </Card>
</CardGroup>