Osadź widżet internetowy

Dodaj agenta głosowego do swojej witryny marketingowej lub wsparcia za pomocą jednego tagu skryptu — odwiedzający rozmawiają z nim bezpośrednio w przeglądarce, bez potrzeby podawania numeru telefonu.

Widżet internetowy zapewnia odwiedzającym Twoją witrynę rozmowę typu kliknij, aby porozmawiać z agentem AI, przy użyciu mikrofonu przeglądarki. To osobny zestaw SDK JavaScript / React z własnym opisem SDK — ten przewodnik koncentruje się na konfiguracji po stronie ThunderPhone, której potrzebuje widżet.

Wymagania wstępne#

1. Utwórz agenta

   Agent, którego prompt i głos będą obsługiwać sesję widżetu. Ustaw widget_enabled: true (wartość domyślna).

2. Wybierz tryb routingu
   • mode="agent" — jeden statyczny agent na klucz. Najprostsza opcja.
   • mode="webhook" — serwer wybiera agenta dla każdego odwiedzającego za pomocą webhooka web.incoming. Użyj tej opcji dla zalogowanych użytkowników, testów A/B lub routingu na poziomie strony.
3. Wymień dozwolone domeny

   Podaj każdą nazwę hosta, która będzie osadzać widżet. Przeglądarki wysyłają origin strony z każdym żądaniem sesji, więc lista uniemożliwia użycie klucza, gdy ktoś skopiuje go na inną witrynę. To nie jest uwierzytelnianie: skrypt poza przeglądarką może wysłać dowolny nagłówek Origin. localhost nie jest automatycznie dozwolony w środowisku produkcyjnym; aby testować lokalnie względem produkcyjnego API, dodaj localhost do listy.

4. Wybierz nadpisania przeglądarki

   Zdecyduj, które ustawienia sesji może wysyłać strona. Nowe klucze nie akceptują żadnych; zobacz Nadpisania przeglądarki.

Utwórz klucz publikowalny#

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

Odpowiedź zawiera key zaczynający się od pk_live_.... Klucze publikowalne są z założenia publiczne — można je bezpiecznie umieścić w pakiecie front-endu. Wszystkie pola znajdziesz w opisie kluczy publikowalnych.

Umieść widżet na swojej stronie#

Trzy opcje integracji opisano w dokumentacji SDK widżetu:

Wszystkie trzy akceptują ten sam publishableKey i renderują przycisk mikrofonu oraz element audio podczas rozmowy.

Nadpisania przeglądarki#

Widżet może wysyłać ze strony cztery ustawienia dla sesji:

Twój klucz publikowalny jest publiczny, więc każdy, kto go posiada, może wysyłać te ustawienia, także ze skryptu podszywającego się pod Twoją domenę. Dlatego wszystkie są domyślnie wyłączone, dopóki nie zezwolisz na nie dla klucza: zaznacz je w sekcji Nadpisania przeglądarki podczas tworzenia lub edytowania widżetu w panelu albo ustaw allowed_overrides za pomocą API kluczy publikowalnych. Zezwalaj tylko na to, co faktycznie wysyła Twoja strona.

Żądanie sesji zawierające ustawienie, na które klucz nie zezwala, kończy się błędem 400 i wskazuje je:

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

Sprawdzenie ma zastosowanie w obu trybach. W trybie webhook dozwolone ustawienie jest również przekazywane do webhooka web.incoming (context trafia jako website_context). Klucze utworzone przed wprowadzeniem tego ustawienia zezwalają na wszystkie cztery opcje, więc istniejące osadzenia nadal działają; wyłącz to, czego nie używasz.

Wartość context widżetu jest skracana do 12 000 znaków (około 3 400 tokenów typowego tekstu angielskiego) i wlicza się do dopłaty za rozmiar promptu. Agent otrzymuje instrukcję, aby traktować ją jako treść strony, a nie jako instrukcje.

Webhooki w trybie widżetu#

Gdy mode="webhook", ThunderPhone wywołuje Twój webhook_url przy każdym rozpoczęciu sesji z ładunkiem web.incoming. Zwróć konfigurację agenta AI, którą chcesz uruchomić dla tego odwiedzającego — korzysta ona z tego samego schematu odpowiedzi co połączenia telefoniczne:

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

Możesz łączyć w prompcie kontekst z własnej sesji (który klient przegląda stronę, na której stronie się znajduje) oraz zmieniać agentów AI dla poszczególnych wdrożeń.

Monitoruj sesje#

Sesje widżetu pojawiają się w GET /v1/calls z direction="widget" — mają ten sam transkrypt, nagranie, ocenę i rozliczenia co połączenia telefoniczne. Filtruj według direction, aby utworzyć panel wyłącznie dla widżetu.

Kolejne kroki#