Įterpkite žiniatinklio valdiklį

Įtraukite balso agentą į savo rinkodaros ar palaikymo svetainę naudodami vieną scenarijaus žymą — lankytojai gali su juo kalbėtis tiesiai naršyklėje, telefono numerio nereikia.

Žiniatinklio valdiklis suteikia jūsų svetainės lankytojams galimybę spustelėjus kalbėti su balso agentu, naudojant naršyklės mikrofoną. Tai atskiras JavaScript / React SDK su savo SDK nuoroda — šiame vadove aptariamas ThunderPhone pusės nustatymas, kurio reikia valdikliui.

Būtinosios sąlygos#

1. Sukurkite agentą

   Agentas, kurio raginimas ir balsas bus naudojami valdiklio sesijoje. Nustatykite widget_enabled: true (numatytoji reikšmė).

2. Pasirinkite nukreipimo režimą
   • mode="agent" — vienas statinis agentas kiekvienam raktui. Paprasčiausia parinktis.
   • mode="webhook" — jūsų serveris parenka agentą kiekvienam lankytojui per web.incoming žiniatinklio kablį. Naudokite tai prisijungusiems naudotojams, A/B testams arba nukreipimui pagal puslapį.
3. Nurodykite leidžiamus domenus

   Nurodykite kiekvieną pagrindinio kompiuterio vardą, kuriame bus įterptas valdiklis. Naršyklės su kiekviena sesijos užklausa siunčia puslapio kilmę, todėl šis sąrašas neleidžia jūsų raktui veikti, kai kas nors jį nukopijuoja į kitą svetainę. Tai nėra autentifikavimas: ne naršyklėje veikiantis scenarijus gali siųsti bet kurią Origin antraštę. Produkcinėje aplinkoje localhost automatiškai neleidžiamas; norėdami testuoti vietoje naudodami produkcinę API, įtraukite localhost į sąrašą.

4. Pasirinkite naršyklės perrašymus

   Nuspręskite, kuriuos sesijos nustatymus gali siųsti jūsų puslapis. Nauji raktai nepriima jokių; žr. Naršyklės perrašymai.

Sukurkite viešinamą raktą#

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

Atsakyme pateikiamas key, prasidedantis pk_live_.... Viešinami raktai pagal paskirtį yra vieši — juos saugu įtraukti į jūsų naudotojo sąsajos paketą. Visus laukus rasite viešinamų raktų nuorodoje.

Įdiekite valdiklį savo svetainėje#

Valdiklio SDK dokumentacijoje aprašytos trys integravimo parinktys:

Visos trys parinktys priima tą patį publishableKey ir pateikia mikrofono mygtuką bei garso elementą pokalbio metu.

Naršyklės pakeitimai#

Valdiklis gali siųsti keturis kiekvienos sesijos nustatymus iš puslapio:

Jūsų publikuojamas raktas yra viešas, todėl bet kas, kas jį turi, gali siųsti šiuos nustatymus, įskaitant iš scenarijaus, imituojančio jūsų domeną. Todėl kiekvienas jų yra išjungtas, kol jo neleidžiate rakte: pažymėkite jį skiltyje Naršyklės perrašymai, kai kuriate arba redaguojate valdiklį valdymo skydelyje, arba nustatykite allowed_overrides per Publikuojamų raktų API. Leiskite tik tai, ką iš tikrųjų siunčia jūsų puslapis.

Sesijos užklausa, kurioje pateikiamas nustatymas, kurio raktas neleidžia, nepavyksta su 400 ir nurodo jį:

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

Patikra taikoma abiem režimais. Žiniatinklio kablio režimu leidžiamas nustatymas taip pat persiunčiamas į jūsų web.incoming žiniatinklio kablį (context pateikiamas kaip website_context). Raktai, sukurti prieš atsirandant šiam nustatymui, leidžia visus keturis, todėl esami įterpimai veikia toliau; išjunkite tai, ko nenaudojate.

Valdiklio context sutrumpinamas iki 12 000 simbolių (maždaug 3 400 įprasto angliško teksto žetonų) ir įskaičiuojamas į raginimo dydžio priemoką. Agentui nurodoma laikyti jį puslapio turiniu, o ne instrukcijomis.

Valdiklio režimo žiniatinklio kabliukai#

Kai mode="webhook", ThunderPhone kiekvienos sesijos pradžioje iškviečia jūsų webhook_url su web.incoming turiniu. Grąžinkite agento konfigūraciją, kurią norite paleisti tam lankytojui — ji atitinka tą pačią atsakymo schemą, kaip ir telefono skambučiams:

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

Į raginimą galite įtraukti kontekstą iš savo sesijos (kuris klientas naršo, kuriame puslapyje jis yra) ir keisti agentus pagal diegimo etapą.

Stebėkite sesijas#

Valdiklio sesijos rodomos GET /v1/calls, kai direction="widget" — su tuo pačiu nuorašu, įrašu, vertinimu ir atsiskaitymu kaip telefono skambučiai. Filtruokite pagal direction, kad sukurtumėte tik valdikliui skirtą ataskaitų sritį.

Kiti veiksmai#