---
title: "Web widget'ını yerleştirin"
description: "Tek bir script etiketiyle pazarlama veya destek sitenize bir sesli AI ajanı ekleyin — ziyaretçiler telefon numarasına gerek olmadan doğrudan tarayıcıdan konuşabilir."
---

Web widget'ı, site ziyaretçilerinize tarayıcının mikrofonunu kullanarak
bir yapay zeka ajanıyla tıklayıp konuşabilecekleri bir görüşme sunar. Bu,
kendi [SDK referansına](/tr/widget/overview) sahip ayrı bir
JavaScript / React SDK'sıdır — bu kılavuz, widget'ın ihtiyaç duyduğu
ThunderPhone tarafındaki kuruluma odaklanır.

<Note>
  Bunların tümünü cURL olmadan yapabilirsiniz: **Web Widget'ları** pano
  sayfası (`/dashboard/web-widgets`) widget'ı oluşturur, modunu
  ve ajanını ayarlar, izin verilen alan adlarını yönetir ve size gömme
  kod parçacığını verir.
</Note>

## Ön koşullar

<Steps>
  <Step title="Bir yapay zeka ajanı oluşturun">
    İstemi ve sesi widget oturumunu çalıştıracak yapay zeka ajanı. Şunu ayarlayın:
    `widget_enabled: true` (varsayılan).
  </Step>
  <Step title="Yönlendirme modunu belirleyin">
    - `mode="agent"` — anahtar başına bir statik ajan. En basit seçenek.
    - `mode="webhook"` — sunucunuz, ziyaretçi başına ajanı bir
      [`web.incoming` webhook'u](/tr/webhooks/call-incoming) aracılığıyla seçer. Bunu
      oturum açmış kullanıcılar, A/B testleri veya sayfa başına yönlendirme için kullanın.
  </Step>
  <Step title="İzin verilen alan adlarını listeleyin">
    Widget'ı gömecek her ana makine adını belirtin. Tarayıcılar her oturum isteğiyle
    sayfanın kaynağını gönderir; bu nedenle liste, biri anahtarınızı başka bir siteye kopyaladığında
    çalışmasını engeller. Bu kimlik doğrulama değildir: tarayıcı dışındaki bir betik herhangi bir `Origin`
    başlığı gönderebilir. `localhost`, üretimde otomatik olarak izinli değildir; üretim API'sine karşı yerel olarak
    test etmek için listeye `localhost` ekleyin.
  </Step>
  <Step title="Tarayıcı geçersiz kılmalarını seçin">
    Sayfanızın hangi oturum ayarlarını gönderebileceğine karar verin. Yeni anahtarlar
    hiçbirini kabul etmez; bkz. [Tarayıcı geçersiz kılmaları](#browser-overrides).
  </Step>
</Steps>

## Yayınlanabilir anahtar oluşturun

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

Yanıt, `pk_live_...` ile başlayan bir `key` içerir. **Yayınlanabilir
anahtarlar tasarım gereği herkese açıktır** — ön uç paketinizle birlikte
güvenle yayınlayabilirsiniz. Tüm alanlar için
[Yayınlanabilir anahtarlar referansına](/api-reference/publishable-keys) bakın.

<Warning>
  `allowed_domains` en az bir giriş içermelidir. `*.example.com`,
  alt alan adlarıyla (ör. `api.example.com`) eşleşir ancak yalın
  alan adıyla **eşleşmez**. `*` veya `*.*` gibi yalın joker karakterler
  reddedilir.
</Warning>

## Widget'ı sitenize ekleyin

Üç entegrasyon seçeneği
[widget SDK belgelerinde](/tr/widget/overview) açıklanmıştır:

<CardGroup cols={3}>
  <Card title="React bileşeni" icon="react" href="/tr/widget/react">
    `<ThunderPhoneWidget publishableKey="pk_live_..." />`.
  </Card>
  <Card title="Arayüzsüz kanca" icon="circle-nodes" href="/tr/widget/headless-hook">
    Özel kullanıcı arayüzleri için `useThunderPhone()`.
  </Card>
  <Card title="CDN betik etiketi" icon="code" href="/tr/widget/cdn-script-tag">
    Paketleyici kullanmayan siteler için `ThunderPhone.mount({...})`.
  </Card>
</CardGroup>

Üçü de aynı `publishableKey` değerini kabul eder ve mikrofon düğmesini
ile arama sırasındaki ses öğesini oluşturur.

## Tarayıcı geçersiz kılmaları

Bileşen, sayfadan oturum başına dört ayar gönderebilir:

| Ayar | Bileşen özelliği | Değiştirdiği şey |
|---------|-------------|-----------------|
| `context` | `context` | Sayfadaki metin, referans olarak ajan istemine eklenir |
| `variables` | yok (`POST /v1/widget/session` yalnızca ham) | İstem içindeki `{{variable}}` yer tutucularının değerleri |
| `voice` | `voice` | Bu oturum için ajanın sesi |
| `language` | `language` | Oturumun başladığı dil |

Yayınlanabilir anahtarınız herkese açıktır; dolayısıyla buna sahip olan herkes, alan adınızı taklit eden bir betik de dahil olmak üzere bu ayarları gönderebilir. Bu nedenle, anahtarda izin verene kadar her biri kapalıdır: kontrol panelinde widget'ı oluştururken veya düzenlerken **Tarayıcı geçersiz kılmaları** altında ilgili seçeneği işaretleyin ya da `allowed_overrides` değerini [Yayınlanabilir anahtarlar API'si](/api-reference/publishable-keys) üzerinden ayarlayın. Yalnızca sayfanızın gerçekten gönderdiği ayarlara izin verin.

Anahtarın izin vermediği bir ayarı içeren oturum isteği `400` ile başarısız olur ve ayarı belirtir:

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

Denetim her iki modda da uygulanır. Web kancası modunda izin verilen bir ayar, `web.incoming` web kancanıza da iletilir (`context`, `website_context` olarak gelir). Bu ayar eklenmeden önce oluşturulan anahtarlar dört ayarın tümüne izin verir; bu nedenle mevcut yerleştirmeler çalışmaya devam eder. Kullanmadığınız ayarları kapatın.

Bileşen `context` değeri 12.000 karakterde kesilir (yaklaşık 3.400 tipik İngilizce metin belirteci) ve [istem boyutu ek ücretine](/tr/guides/billing-and-topups) dahil edilir. Yapay zeka ajanına bunun talimatlar değil, sayfa içeriği olarak ele alınması söylenir.

## Widget modu webhook'ları

`mode="webhook"` olduğunda ThunderPhone, her oturum başlangıcında
`web.incoming` yüküyle `webhook_url` adresinizi çağırır. Bu ziyaretçi için
çalıştırmak istediğiniz yapay zeka ajanı yapılandırmasını döndürün — telefon
aramalarıyla aynı [yanıt şemasını](/tr/webhooks/call-incoming) izler:

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

Kendi oturumunuzdaki bağlamı (hangi müşterinin göz attığını,
hangi sayfada olduklarını) isteme ekleyebilir ve her yayına alma süreci
için ajanları değiştirebilirsiniz.

## Oturumları izleyin

Widget oturumları,
[`GET /v1/calls`](/api-reference/calls#list-calls) içinde
`direction="widget"` ile görünür — telefon çağrılarıyla aynı transkript,
kayıt, değerlendirme ve faturalandırma uygulanır. Yalnızca widget'a özel
bir pano oluşturmak için `direction` ile filtreleyin.

---

## Sonraki adımlar

<CardGroup cols={2}>
  <Card title="Widget SDK referansı" icon="window-maximize" href="/tr/widget/overview">
    React / hook / CDN entegrasyon ayrıntıları.
  </Card>
  <Card title="Çağrı başına dinamik yapılandırma" icon="bolt" href="/tr/guides/dynamic-call-config">
    `mode="webhook"` akışını uçtan uca uygulayın.
  </Card>
  <Card title="Yayınlanabilir anahtarlar referansı" icon="key" href="/api-reference/publishable-keys">
    Anahtar kaynağındaki tüm alanlar.
  </Card>
  <Card title="Mikrofon oturumları API'si" icon="microphone" href="/api-reference/mic-sessions">
    Widget'ı atlayın; özel arayüzler için LiveKit'i doğrudan kullanın.
  </Card>
</CardGroup>