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

# Widget Suara yang Dapat Disematkan

> 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="https://mintcdn.com/thunderphone/4XhPaCl4RGfyS7_M/images/widget-showcase.png?fit=max&auto=format&n=4XhPaCl4RGfyS7_M&q=85&s=17fea4fe853f3548b9b2628c9d4c4fc0" alt="Widget ThunderPhone dalam tema terang dan gelap dengan berbagai warna aksen" width="1200" height="800" data-path="images/widget-showcase.png" />
</Frame>

## Prasyarat

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

<Steps>
  <Step title="Buat kunci API yang dapat dipublikasikan">
    Buka **Pengembang** di pengaturan dashboard dan buat kunci yang dapat dipublikasikan. Kunci yang dapat dipublikasikan diawali dengan `pk_live_` dan aman untuk disertakan dalam kode sisi klien.
  </Step>

  <Step title="Konfigurasikan domain yang diizinkan">
    Dalam pengaturan Pengembang yang sama, tambahkan domain tempat widget akan disematkan. `localhost` selalu diizinkan untuk pengembangan. Karakter pengganti didukung (misalnya, `*.example.com`).
  </Step>

  <Step title="Buat widget web">
    Buka **Widget Web** di dashboard dan buat widget. Pilih agen yang ingin Anda tampilkan dan kunci yang dapat dipublikasikan untuk digunakan. Agen ditentukan secara otomatis dari konfigurasi kunci yang dapat dipublikasikan.
  </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>

***

## Mulai Cepat

Instal paket:

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

Tambahkan widget ke aplikasi Anda:

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

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) theme={null}
  <ThunderPhoneWidget
    publishableKey="pk_live_your_publishable_key"
  />
  ```

  ```tsx Dark theme with custom color theme={null}
  <ThunderPhoneWidget
    publishableKey="pk_live_your_publishable_key"
    theme="dark"
    primaryColor="#8b5cf6"
    title="Ask our AI"
  />
  ```
</CodeGroup>

Tiga prop lainnya menyesuaikan sesi, bukan tampilannya -- semuanya diteruskan ke permintaan sesi saat panggilan dimulai:

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

***

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