Skip to main content
Widżet internetowy zapewnia odwiedzającym Twoją witrynę rozmowę typu kliknij, aby porozmawiać z agentem AI, korzystając z mikrofonu przeglądarki. To osobny zestaw SDK JavaScript / React z własną dokumentacją referencyjną SDK — ten przewodnik skupia się na konfiguracji po stronie ThunderPhone wymaganej przez widżet.
Możesz zrobić to wszystko bez cURL: strona panelu Widżety internetowe (/dashboard/web-widgets) tworzy widżet, ustawia jego tryb i agenta, zarządza dozwolonymi domenami oraz przekazuje fragment kodu do osadzenia.

​
Wymagania wstępne

1

Utwórz agenta

Agent, którego prompt i głos będą używane podczas sesji widżetu. Ustaw widget_enabled: true (wartość domyślna).
2

Wybierz tryb routingu

  • mode="agent" — jeden statyczny agent na klucz. Najprostsze rozwiązanie.
  • mode="webhook" — Twój serwer wybiera agenta dla każdego odwiedzającego za pomocą webhooka web.incoming. Użyj tego w przypadku zalogowanych użytkowników, testów A/B lub routingu zależnego od strony.
3

Wymień dozwolone domeny

Klucze publiczne są ograniczone do originów. Musisz podać każdą nazwę hosta, która będzie osadzać widżet. localhost / 127.0.0.1 są zawsze dozwolone podczas programowania lokalnego.

​
Utwórz klucz publiczny

Odpowiedź zawiera key zaczynający się od pk_live_.... Klucze publiczne są publiczne z założenia — można je bezpiecznie umieścić w pakiecie front-endu. Wszystkie pola znajdziesz w dokumentacji referencyjnej kluczy publicznych.
allowed_domains musi zawierać co najmniej jeden wpis. *.example.com dopasowuje subdomeny (np. api.example.com), ale nie domenę główną. Ogólne symbole wieloznaczne, takie jak * lub *.*, są odrzucane.

​
Dodaj widżet do swojej witryny

Trzy opcje integracji opisano w dokumentacji SDK widżetu:

Komponent React

<ThunderPhoneWidget publishableKey="pk_live_..." />.

Hook headless

useThunderPhone() dla niestandardowych interfejsów użytkownika.

Tag skryptu CDN

ThunderPhone.mount({...}) dla witryn bez bundlera.
Wszystkie trzy akceptują ten sam publishableKey i renderują przycisk mikrofonu oraz element audio podczas połączenia. Pole context widżetu jest obcinane do 12 000 znaków (około 3400 tokenów typowego tekstu angielskiego) i jest uwzględniane w dopłacie za rozmiar promptu.

​
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, którą chcesz uruchomić dla tego odwiedzającego — stosuje ona ten sam schemat odpowiedzi co połączenia telefoniczne:
Możesz włączyć do promptu kontekst z własnej sesji (który klient przegląda witrynę, na której stronie się znajduje) oraz zmieniać agentów dla poszczególnych wdrożeń.

​
Monitoruj sesje

Sesje widżetu pojawiają się w GET /v1/calls z direction="widget" — z tym samym transkryptem, nagraniem, oceną i rozliczeniem co połączenia telefoniczne. Filtruj według direction, aby utworzyć panel tylko dla widżetu.

​
Kolejne kroki

Dokumentacja SDK widżetu

Szczegóły integracji React / hook / CDN.

Dynamiczna konfiguracja dla każdego połączenia

Zaimplementuj kompleksowo przepływ mode="webhook".

Dokumentacja kluczy publikowalnych

Każde pole zasobu klucza.

API sesji mikrofonu

Pomiń widżet; steruj LiveKit bezpośrednio, aby tworzyć niestandardowe interfejsy użytkownika.