Developer cookbook

Integrați widgetul web

Adăugați un agent vocal pe site-ul dumneavoastră de marketing sau de asistență cu un singur tag de script — vizitatorii vorbesc cu acesta direct din browser, fără a fi necesar un număr de telefon.

Widgetul web le oferă vizitatorilor site-ului dumneavoastră o conversație prin clic pentru a vorbi cu un agent vocal cu IA, folosind microfonul browserului. Este un SDK JavaScript / React separat, cu propria referință SDK — acest ghid se concentrează pe configurarea din ThunderPhone necesară widgetului.

Cerințe preliminare#

1. Creați un agent

   Agentul ale cărui instrucțiuni și voce vor rula sesiunea widgetului. Setați widget_enabled: true (valoarea implicită).

2. Alegeți modul de rutare
   • mode="agent" — un agent static pentru fiecare cheie. Cea mai simplă opțiune.
   • mode="webhook" — serverul dumneavoastră alege agentul pentru fiecare vizitator printr-un webhook web.incoming. Utilizați această opțiune pentru utilizatori autentificați, teste A/B sau rutare în funcție de pagină.
3. Enumerați domeniile permise

   Cheile publicabile sunt blocate la origine. Trebuie să specificați fiecare nume de gazdă care va încorpora widgetul. localhost / 127.0.0.1 sunt întotdeauna permise în timpul dezvoltării locale.

Creați o cheie publicabilă#

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

Răspunsul include o key care începe cu pk_live_.... Cheile publicabile sunt publice prin concepție — pot fi incluse în siguranță în pachetul front-end. Consultați referința cheilor publicabile pentru toate câmpurile.

Adăugați widgetul pe site-ul dumneavoastră#

Sunt disponibile trei opțiuni de integrare în documentația SDK a widgetului:

Toate cele trei opțiuni acceptă aceeași publishableKey și redau butonul de microfon plus elementul audio din apel.

context al widgetului este trunchiat la 12.000 de caractere (aproximativ 3.400 de tokenuri din text englez obișnuit) și este luat în calcul pentru suprataxa pentru dimensiunea instrucțiunilor.

Webhookuri pentru modul widget#

Când mode="webhook", ThunderPhone apelează webhook_url la fiecare început de sesiune cu un payload web.incoming. Returnați configurația agentului pe care doriți să îl rulați pentru acel vizitator — aceasta urmează aceeași schemă de răspuns ca apelurile telefonice:

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

Puteți combina în instrucțiuni contextul din propria sesiune (ce client navighează, pe ce pagină se află) și puteți schimba agenții pentru fiecare lansare graduală.

Monitorizați sesiunile#

Sesiunile widget apar în GET /v1/calls cu direction="widget" — aceeași transcriere, înregistrare, evaluare și facturare ca apelurile telefonice. Filtrați după direction pentru a crea un tablou de bord doar pentru widget.

Pașii următori#