---
title: "Widget Suara yang Dapat Disematkan"
description: "Tambahkan agen suara AI ke situs web apa pun dengan beberapa baris kode"
---

Widget suara ThunderPhone yang dapat disematkan memungkinkan pengunjung situs web Anda berbicara dengan agen AI langsung dari browser. Tidak memerlukan panggilan telepon -- pengguna cukup mengeklik tombol dan memulai percakapan suara real-time yang didukung oleh ThunderPhone.

Widget dirender sebagai bilah bergaya glassmorphism yang menyesuaikan dengan tema terang dan gelap, dengan warna aksen dan posisi yang dapat disesuaikan. Widget didistribusikan sebagai paket npm `@thunderphone/widget` dan juga tersedia melalui CDN untuk lingkungan tanpa bundler.

<Frame>
  <img src="/images/widget-showcase.png" alt="Widget ThunderPhone dalam tema terang dan gelap dengan berbagai warna aksen" />
</Frame>

## Prasyarat

Sebelum menyematkan widget, selesaikan tiga langkah berikut di [Dashboard ThunderPhone](https://app.thunderphone.com):

<Steps>
<Step title="Buat widget web">
  Buka **Widget Web** di dasbor dan buat widget. Pilih agen yang ingin Anda tampilkan. Setiap widget memiliki kunci yang dapat dipublikasikan sendiri (`pk_live_...`), yang aman disertakan dalam kode sisi klien; agen ditentukan dari kunci tersebut.
</Step>

<Step title="Konfigurasikan domain yang diizinkan">
  Pada widget yang sama, tambahkan domain tempat widget akan disematkan. Karakter pengganti didukung (misalnya, `*.example.com`). Daftar ini mencegah widget berfungsi ketika seseorang menyalin kunci Anda ke situs lain; ini bukan autentikasi, karena skrip di luar browser dapat mengirim header `Origin` apa pun. `localhost` tidak diizinkan secara otomatis dalam produksi: tambahkan ke daftar untuk menguji secara lokal terhadap API produksi.
</Step>

<Step title="Pilih penggantian browser">
  Jika halaman Anda menetapkan `language`, `voice`, atau `context`, aktifkan masing-masing di bawah **Penggantian browser**. Widget baru tidak menerima penggantian apa pun, dan permintaan sesi yang membawa pengaturan yang dinonaktifkan gagal dengan `400 override_not_allowed`. Lihat [Penggantian browser](/id/guides/embed-web-widget).
</Step>
</Steps>

<Warning>
  Kunci yang dapat dipublikasikan (`pk_live_...`) **bukan** token API rahasia Anda. Kunci yang dapat dipublikasikan dirancang untuk penggunaan sisi klien dan dibatasi pada sesi widget di domain yang Anda izinkan. Jangan pernah gunakan token API rahasia Anda dalam kode sisi klien.
</Warning>

<Note>
  Sesi widget berakhir setelah 30 menit secara default, atau lebih cepat jika durasi panggilan maksimum agen lebih singkat. Ubah batas per kunci dengan `max_call_duration_seconds` pada [kunci yang dapat dipublikasikan](/api-reference/publishable-keys) (hingga 6 jam), atau tetapkan ke `null` untuk menggunakan batas agen sendiri.
</Note>

---

## Mulai Cepat

Instal paket:

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

Tambahkan widget ke aplikasi Anda:

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

Selesai. Pengguna Anda akan melihat bilah panggilan bergaya glassmorphism yang menghubungkan mereka ke agen AI Anda dengan satu klik.

---

## Kustomisasi

Widget memiliki empat prop tampilan:

| Prop | Default | Deskripsi |
|------|---------|-------------|
| `theme` | `'light'` | `'light'` untuk kaca putih, `'dark'` untuk kaca gelap |
| `primaryColor` | `'#000000'` (terang) / `'#ffffff'` (gelap) | Warna aksen untuk tombol mulai, bentuk gelombang, dan indikator penyambungan |
| `title` | `'Voice assistant'` | Teks yang ditampilkan dalam widget |
| `position` | `'bottom-right'` | Sudut viewport: `'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>

Tiga prop lainnya menyesuaikan sesi, bukan tampilan -- semuanya diteruskan ke permintaan sesi saat panggilan dimulai. Masing-masing hanya berfungsi jika kunci publik widget mengizinkannya melalui **Override browser**; jika tidak, permintaan sesi gagal dengan `400 override_not_allowed`:

| Prop | Deskripsi |
|------|-------------|
| `language` | Penggantian bahasa per sesi -- kode atau lokal seperti `en`, `es`, atau `fr-FR` |
| `voice` | Penggantian suara per sesi -- nama suara seperti `maria` |
| `context` | Konteks faktual halaman atau situs yang diteruskan ke agen (dipotong di sisi server hingga 12.000 karakter) |

Lihat [referensi komponen React](/id/widget/react) untuk tabel prop lengkap.

Untuk UI yang sepenuhnya kustom, gunakan [hook headless](/id/widget/headless-hook) untuk mengelola sesi suara sambil membangun antarmuka Anda sendiri. Hook ini menyediakan level audio real-time untuk membangun visualisasi yang reaktif terhadap audio.

Setiap percakapan widget adalah sebuah panggilan. Ini diperhitungkan dalam [batas panggilan bersamaan](/api-reference/introduction#call-limits) organisasi Anda (secara default 20 panggilan sedang berlangsung, dibagikan dengan panggilan telepon dan panggilan lainnya) serta batas widget sebesar 25 sesi aktif (atau batas panggilan bersamaan Anda, jika lebih tinggi). Pada salah satu batas tersebut, percakapan baru tidak dapat dimulai hingga sebuah panggilan berakhir.

---

## Opsi Integrasi

Pilih metode integrasi yang sesuai dengan stack Anda:

<CardGroup cols={3}>
  <Card title="Komponen React" icon="react" href="/id/widget/react">
    Komponen UI siap pakai dengan kontrol panggilan dan tampilan status bawaan. Impor, berikan props, selesai.
  </Card>
  <Card title="Hook Headless" icon="code" href="/id/widget/headless-hook">
    Kontrol penuh atas UI. Hook `useThunderPhone` mengelola sesi suara saat Anda membangun antarmuka sendiri.
  </Card>
  <Card title="CDN / Tag Skrip" icon="globe" href="/id/widget/cdn-script-tag">
    Tidak memerlukan bundler. Muat widget melalui tag skrip untuk situs statis, WordPress, dan lingkungan non-React lainnya.
  </Card>
</CardGroup>

---

## Gaya

Widget dilengkapi tema terang dan gelap bawaan yang dikontrol oleh prop `theme`, serta warna aksen yang dikontrol oleh prop `primaryColor`. Untuk penyesuaian lebih mendalam, Anda dapat mengganti properti dan kelas kustom CSS. Lihat [panduan Gaya](/id/widget/styling) untuk detail.

<Note>
  Butuh bantuan? Hubungi kami di [support@thunderphone.com](mailto:support@thunderphone.com)
</Note>