Web widget

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 sahip ayrı bir JavaScript / React SDK'sıdır — bu kılavuz, widget'ın ihtiyaç duyduğu ThunderPhone tarafındaki kuruluma odaklanır.

Ön koşullar#

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

2. 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 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.
3. İ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.

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

Yayınlanabilir anahtar oluşturun#

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"]
  }'

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"]
  }'

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 bakın.

Widget'ı sitenize ekleyin#

Üç entegrasyon seçeneği widget SDK belgelerinde açıklanmıştır:

Üçü 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:

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

{
  "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 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ı izler:

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