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 al cărui prompt și a cărui voce vor rula sesiunea widgetului. Setați widget_enabled: true (valoarea implicită).

2. Decideți modul de rutare
   • mode="agent" — un agent static per 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 per pagină.
3. Enumerați domeniile permise

   Indicați fiecare nume de gazdă care va încorpora widgetul. Browserele trimit originea paginii cu fiecare solicitare de sesiune, astfel încât lista împiedică cheia dumneavoastră să funcționeze când cineva o copiază pe alt site. Aceasta nu este autentificare: un script din afara unui browser poate trimite orice antet Origin. localhost nu este permis automat în producție; pentru a testa local cu API-ul de producție, adăugați localhost în listă.

4. Alegeți suprascrierile din browser

   Decideți ce setări de sesiune poate trimite pagina dumneavoastră. Cheile noi nu acceptă niciuna; consultați Suprascrieri din browser.

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

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.

Suprascrieri din browser#

Widgetul poate trimite patru setări per sesiune din pagină:

Cheia dvs. publicabilă este publică, astfel încât oricine o are poate trimite aceste setări, inclusiv dintr-un script care imită domeniul dvs. Prin urmare, fiecare este dezactivată până când o permiteți pentru cheie: bifați-o la Suprascrieri din browser când creați sau editați widgetul în tabloul de bord ori setați allowed_overrides prin API-ul pentru chei publicabile. Permiteți doar ceea ce trimite efectiv pagina dvs.

O solicitare de sesiune care include o setare nepermisă de cheie eșuează cu 400 și o menționează:

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

Verificarea se aplică în ambele moduri. În modul webhook, o setare permisă este transmisă și către webhookul dumneavoastră web.incoming (context ajunge ca website_context). Cheile create înainte să existe această setare permit toate patru, astfel încât integrările existente continuă să funcționeze; dezactivați ce nu utilizați.

context al widgetului este trunchiat la 12.000 de caractere (aproximativ 3.400 de tokenuri de text englezesc obișnuit) și este luat în calcul pentru suplimentul pentru dimensiunea promptului. Agentului i se spune să îl trateze ca pe conținutul paginii, nu ca pe instrucțiuni.

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#