Vloženie webového widgetu

Webový widget umožňuje návštevníkom vašej stránky konverzáciu s hlasovým agentom po kliknutí pomocou mikrofónu prehliadača. Ide o samostatné JavaScript / React SDK s vlastnou referenciou SDK — tento návod sa zameriava na nastavenie na strane ThunderPhone, ktoré widget potrebuje.

Predpoklady

1. Vytvorte agenta

   Agent, ktorého prompt a hlas budú spúšťať reláciu widgetu. Nastavte widget_enabled: true (predvolená hodnota).

2. Rozhodnite o režime smerovania
   • mode="agent" — jeden statický agent pre každý kľúč. Najjednoduchšie riešenie.
   • mode="webhook" — váš server vyberie agenta pre každého návštevníka prostredníctvom webhooku web.incoming. Použite ho pre prihlásených používateľov, A/B testy alebo smerovanie podľa stránky.
3. Uveďte povolené domény

   Publikovateľné kľúče sú viazané na pôvod. Musíte uviesť každý názov hostiteľa, do ktorého bude widget vložený. localhost / 127.0.0.1 sú počas lokálneho vývoja vždy povolené.

Vytvorte publikovateľný kľúč

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

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

Odpoveď obsahuje key začínajúci na pk_live_.... Publikovateľné kľúče sú verejné už z princípu — je bezpečné zahrnúť ich do balíka front-endu. Všetky polia nájdete v referencii publikovateľných kľúčov.

Vložte widget na svoju stránku

V dokumentácii SDK widgetu sú popísané tri možnosti integrácie:

Všetky tri prijímajú rovnaký publishableKey a vykreslia tlačidlo mikrofónu aj zvukový prvok počas hovoru.

context widgetu je skrátený na 12 000 znakov (približne 3 400 tokenov typického anglického textu) a započítava sa do príplatku za veľkosť promptu.

Webhooky režimu widgetu

Keď mode="webhook", ThunderPhone zavolá vaše webhook_url pri každom začatí relácie s dátami web.incoming. Vráťte konfiguráciu agenta, ktorú chcete spustiť pre daného návštevníka — používa rovnakú schému odpovede ako telefónne hovory:

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

Do promptu môžete pridať kontext z vlastnej relácie (ktorý zákazník prehliada stránku, na ktorej stránke sa nachádza) a meniť agentov podľa jednotlivých nasadení.

Monitorovanie relácií

Relácie widgetu sa zobrazujú v GET /v1/calls s direction="widget" — majú rovnaký prepis, nahrávku, hodnotenie a fakturáciu ako telefonické hovory. Filtrujte podľa direction a vytvorte si panel len pre widget.

Ďalšie kroky