ThunderPhone v3 je dostupan.Postavite sve sami, već od 2 ¢/min.Pročitajte objavu

Developer cookbook

Varijable i kontekst po pozivu

Svakom pozivu dodijelite vlastite pojedinosti, kao imenovane varijable za upit ili slobodno oblikovani sažetak, bez promjene agenta.

Svaki poziv može sadržavati dvije vrste unosa po pozivu. Upotrijebite jednu ili obje zajedno:

  • variables: imenovane vrijednosti koje popunjavaju {{placeholders}} u promptu. Upotrijebite ih za polja na koja se prompt poziva imenom, kao što su ime pozivatelja, broj računa ili termin sastanka.
  • context: tekst slobodnog oblika dodan nakon prompta. Upotrijebite ga za sažetak koji ne odgovara predlošku, kao što je opis zadatka za ovaj poziv ili ranije prikupljene bilješke.

Oboje funkcionira sa spremljenim agentom i s umetnutom konfiguracijom, pri svakom načinu pokretanja poziva opisanom u nastavku. Nijedno ne mijenja spremljenog agenta, njegovu povijest verzija ni ostale postavke.

{
  "agent_id": 12,
  "variables": {"name": "Ada", "appointment_slot": "Tuesday at 10 AM"},
  "context": "Ada rescheduled twice last month. She prefers mornings and asked us not to call her work number."
}

Varijable

Postavite rezervirana mjesta u prompt spremljenog agenta, a zatim pri pokretanju poziva navedite objekt variables. ThunderPhone prikazuje tekst prije slanja konfiguracije poziva u glasovno izvođenje.

Kada vrijednosti nisu potrebne, izostavite variables; nemojte slati null (odbijeno s 400).

Rezervirana mjesta i zadane vrijednosti

You are calling {{name|Friend}} about account {{account_id}}.
The available appointment is {{ appointment_slot }}.

Nazivi razlikuju velika i mala slova te slijede obrazac [A-Za-z_][A-Za-z0-9_]*. Razmaci oko naziva su dopušteni; razmak nakon znaka | dio je zadane vrijednosti i zadržava se. {{name|Friend}} koristi Friend kada name nedostaje ili je null; prazan niz izričito je navedena vrijednost. Nedostajuće vrijednosti bez zadane vrijednosti postaju prazni nizovi, a njihovi se nazivi prikazuju u unresolved_variables. Tekst između dvostrukih vitičastih zagrada koji nije valjano rezervirano mjesto uklanja se. Tekst u dvostrukim vitičastim zagradama unutar svake navedene vrijednosti uklanja se neovisno; vrijednost ne može ukloniti okolni tekst prompta ni drugu vrijednost. Uklanjaju se i neupareni razdjelnici s dvostrukim vitičastim zagradama. Primjeri JSON-a u promptovima ne smiju koristiti {{. Vrijednosti su običan tekst, nikada se ne izvršavaju kao kod niti se rekurzivno proširuju kao predlošci.

Varijable se mogu pojaviti i u promptovima za potvrdu, odlaznim porukama govorne pošte te tekstu obavijesti o pristanku kada se to polje šalje za telefonski poziv. Agent nema zasebno polje first_message: njegove uvodne upute stavite u prompt. Postojeća rezervirana mjesta govorne pošte {agent_name} i {org_name} nastavljaju raditi.

Vrijednosti i ograničenja

Vrijednosti mogu biti nizovi znakova, brojevi, Booleove vrijednosti ili null; Booleove vrijednosti prikazuju se kao true i false. Upravljački znakovi Unicodea (Cc), osim novog retka (\n), tabulatora (\t) i povrata retka (\r), znaci oblikovanja (Cf), osim spojnika i nespojnika nulte širine (U+200C, U+200D, koji tvore riječi u indijskim jezicima i jezicima koji koriste arapsko pismo), te kodne točke zamjenskog područja (Cs) uklanjaju se; \r\n normalizira se u \n. Svaka je vrijednost ograničena na 2.000 znakova pri prikazu. Dostavljeni nizovi znakova također se čiste i skraćuju prije pohrane. Izvorni objekt mora stati u 32 KB UTF-8 JSON-a; veći objekti dobivaju 400 u zahtjevima za poziv/sesiju, dok uvozi kampanja pojedinačno prijavljuju neispravne retke. Nizovi i ugniježđeni objekti nisu prihvaćeni kao vrijednosti. Metapodaci s ključevima koji ne odgovaraju (primjerice zaglavlje CSV-a s razmakom) zadržavaju se i vraćaju, ali se ne mogu referencirati zamjenskim mjestom.

Kontekst

context je niz znakova do 20.000 znakova. ThunderPhone ga dodaje nakon uputa, kada se popune varijable uputa, kao omeđeni blok:

<your prompt, with its variables filled in>
 
Details for this call:
<call_context>
Ada rescheduled twice last month. She prefers mornings and asked us not to call her work number.
</call_context>

Agent ga čita zajedno sa svojim uputama, stoga ga napišite onako kako biste prije poziva informirali kolegu. Kontekst nije predložak: {{name}} unutar njega ostaje kako je napisano. Ako tekst treba vrijednost, sami je unesite prije slanja.

  • null, prazan niz ili samo razmaci znače da nema konteksta.
  • Vrijednost koja nije niz ili je dulja od 20.000 znakova odbija se s kodom 400 u zahtjevima za pozive i sesije; iz konfiguracijskog webhooka razmjena ne uspijeva kao i kod nevaljanog variables (pogledajte u nastavku).
  • Uklanjaju se početni i završni razmaci te isti kontrolni i oblikovni znakovi kao i u vrijednostima varijabli.
  • Kontekst je dio prompta poziva, stoga se uračunava u veličinu prompta.

Kod agenta s koracima, kontekst slijedi nakon uputa svakog agenta u pozivu, a ne nakon uputa svakog koraka.

Odakle dolaze vrijednosti

Izlazni API

Pošaljite variables i context u zahtjevu POST /v1/call:

{
  "from_number": "+15551234567",
  "to_number": "+14155552671",
  "agent_id": 12,
  "variables": {
    "name": "Ada",
    "account_id": "A-17",
    "appointment_slot": "Tuesday at 10 AM"
  },
  "context": "Ada asked to be called back about the late fee on her March invoice."
}

Oboje funkcionira i sa zadanim odlaznim agentom glasovnog broja ili s umetnutim config.prompt. S umetnutom konfiguracijom, context može biti i unutar config, što je isto polje koje vraća webhook za konfiguraciju; ako pošaljete oboje, moraju sadržavati isti tekst. Ključ idempotentnosti ne može se ponovno upotrijebiti s različitim varijablama ili drukčijim kontekstom.

CSV kampanje

CSV stupci koji nisu telefonski već su pohranjeni kao varijable kontakta. Svako biranje sada ih automatski koristi. Upotrijebite zaglavlja kao što su name, account_id i appointment_slot kako bi odgovarala vašim rezerviranim mjestima. Postojeće mapiranje imena može kombinirati stupce imena i prezimena u varijablu name. Kontakti kampanje nemaju kontekst po kontaktu.

Webhook za dinamičku konfiguraciju

Na putanji blokirajućeg webhooka za konfiguraciju vratite spremljenog agenta u svojoj organizaciji zajedno sa svim vrijednostima po pozivu. Za agenta Full duplex poziv zadržava glas agenta čak i kada započne na drugom podržanom jeziku: mapiranja glasova po jeziku i izvorno prebacivanje glasova ne primjenjuju se na taj poziv.

{
  "agent_id": 12,
  "variables": {"name": "Ada", "account_id": "A-17"},
  "context": "[REDACTED_LITERAL]"
}
{
  "agent_id": 12,
  "variables": {"name": "Ada", "account_id": "A-17"},
  "context": "Ada called yesterday about a leak in unit 4B; a plumber is booked for Friday."
}

Varijable odgovora prepisuju varijable na razini zahtjeva, dok ostali ključevi zahtjeva ostaju. Vrijednost odgovora null odabire zadanu vrijednost rezerviranog mjesta. Spojeni objekt također mora stati u 32 KB. Odgovori spremljenog agenta prihvaćaju samo agent_id, variables, context, language i vremensku zonu po pozivu timezone; vratite umetnutu konfiguraciju kada trebate zamijeniti prompt ili druge postavke. Webhook odgovori spremljenog agenta upotrebljavaju implementiranu A/B podjelu agenta i za telefonske pozive i za pozive putem widgeta; varijable se prikazuju nakon odabira varijante. Kada odgovor postavi language za agenta koji nije Full duplex, poziv također koristi vlastiti glas tog jezika ako agent ima postavljen glas za taj jezik. Odgovor koji sadrži prompt uvijek upotrebljava umetnutu konfiguraciju: svaki agent_id u tom odgovoru zanemaruje se, uključujući null ili metapodatke koji nisu cijeli broj. Umetnuti prompt i dalje mora proći uobičajenu provjeru valjanosti. Umetnuti webhook odgovori također mogu sadržavati variables i context. context koji nije niz znakova ili je predugačak uzrokuje neuspjeh razmjene: telefonski poziv se odbija, a zahtjev za sesiju widgeta ne uspijeva s 400. Webhook odgovori spremljenog agenta upotrebljavaju implementiranu A/B podjelu agenta i za telefonske pozive i za pozive putem widgeta; varijable se prikazuju nakon odabira varijante. Za dolazne telefonske pozive upotrijebite broj bez dodijeljenog dolaznog agenta i konfigurirajte webhook njegova telefonskog broja ili organizacije; ključevi widgeta upotrebljavaju mode="webhook". Dolazne obavijesti sustava krajnjih točaka ne pružaju blokirajuće konfiguracijske odgovore.

Webhook za postavljanje poziva agenta

Kako bi broj ostao dodijeljen svojem agentu i kako biste popunili samo vrijednosti poziva, agentu dodajte webhook za postavljanje poziva. Prije svakog dolaznog poziva na broj na koji se agent javlja, webhook prima poziv te ID, naziv i verziju agenta, a odgovara istim vrijednostima variables, context, language i timezone za pojedini poziv kao gore, bez potrebe za agent_id. Agent čije postavke koriste rezervirano mjesto bez zadane vrijednosti treba ovaj webhook kako bi se javio na telefonski broj: poziv se ne pokreće kada webhook ne uspije. Rezervirana mjesta sa zadanom vrijednošću, poput {{name|there}}, omogućuju agentu da se javi bez njega.

SIP zaglavlja

Pozivi koji dođu do agenta putem SIP-a (SIP adresa ili broj na ručnoj SIP vezi) mogu prenositi kontekst u zaglavljima X-* i User-to-User. Svako od njih postaje varijabla sip_, kao što su {{sip_x_amzn_connectcontactid}} ili {{sip_uui}}, s najnižim prioritetom: prednost ima vrijednost istog naziva iz API-ja ili webhooka. Pogledajte Prosljeđivanje konteksta poziva u SIP zaglavljima. Vrijednosti zaglavlja postavlja pošiljatelj, stoga ih tretirajte kao nepouzdane, kao i svaku vrijednost koju dostavlja preglednik.

API sesije widgeta

POST /v1/widget/session prihvaća variables i language na najvišoj razini. Njegov javni ključ odabire spremljenog agenta. Ključevi u načinu rada webhooka prosljeđuju te vrijednosti webhooku za konfiguraciju i spajaju odgovor kako je gore opisano. variables widgeta koje isporučuje preglednik pod kontrolom su klijenta, prosljeđuju se doslovno u web.incoming nakon gore opisane provjere i čišćenja nizova te se vraćaju u webhookovima dovršetka i povijesti poziva. Nemojte ih tretirati kao pouzdane podatke za identitet ili autorizaciju.

Vlastito polje preglednika context widgeta razlikuje se: prenosi tekst sa stranice na kojoj se posjetitelj nalazi, koji agent tretira kao sadržaj web-mjesta (pogledajte Ugradite web-widget). Kontekst po pozivu za poziv widgeta dolazi iz webhooka konfiguracije ključa u načinu rada webhooka, kao gore. Kada poziv ima oba, kontekst po pozivu dolazi prvi, a zatim sadržaj stranice.

API sesije u stvarnom vremenu

POST /v1/realtime/sessions prihvaća variables, context i language na najvišoj razini uz agent_id ili ugrađeni config:

{
  "agent_id": 12,
  "variables": {"name": "Ada"},
  "context": "Ada is calling from the front desk about a guest's lost key card."
}

context se navodi samo na najvišoj razini; ugrađeni config odbija ga kao nepoznato polje.

Realtime WebSocket

Sa spremljenim agentom, implementirani prompt spremljenog agenta ostaje njegov prompt. session.instructions postaje kontekst poziva, session.prompt.variables (ili session.config.variables) postaju njegove varijable, a session.language postaje jezik za taj poziv. Odaberite agenta pomoću session.prompt.id u prvom session.update, koji pokreće sesiju čim to ažuriranje stigne:

{
  "type": "session.update",
  "session": {
    "type": "realtime",
    "prompt": {"id": "12", "variables": {"name": "Ada"}},
    "instructions": "Ada asked for a callback about her delivery window."
  }
}

?agent_id=12 u URL-u veze pokreće agenta čim se socket poveže, prije bilo kojeg session.update, pa nema ulaz po pozivu. Dodajte &wait_for_session_update=1 za čekanje prvog session.update i korištenje njegovih uputa i varijabli.

U umetnutoj sesiji (bez spremljenog agenta), session.instructions je sam upit, kao i prije. Pozivi za testiranje mikrofona u alatu Builder i simulirani testni pozivi razrješavaju zadane vrijednosti i nedostajuće rezervirana mjesta, ali nemaju varijable ni ulaz konteksta po pozivu.

Nakon poziva

GET /v1/calls, GET /v1/calls/{call_id}, telephony.complete i web.complete uključuju konačne spojene variables i unresolved_variables. Naslijeđeni tereti dovršetka koji uključuju data.history također ih uključuju:

{
  "variables": {"name": "Ada", "account_id": "A-17"},
  "unresolved_variables": ["appointment_slot"]
}

prompt_snapshot poziva (GET /v1/calls/{call_id}) prikazuje upit agenta s popunjenim varijablama i dodanim blokom konteksta.

Spremite svoj CRM ili identifikator zadatka u objekt varijabli da biste dovršeni poziv povezali s izvornim zapisom. Varijable i kontekst čuvaju se uz zapis poziva; šaljite samo informacije koje je primjereno zadržati u povijesti poziva i webhookovima.

Reprize poziva, u skupovima za provjeru, izvršavanjima repriza i istragama, koriste varijable i kontekst tog poziva s upitom koji se testira, pa repriza testira ono što bi agentu u tom pozivu bilo rečeno.

Kompatibilnost s postojećim upitima

Renderiranje se primjenjuje i na postojeće upite spremljenih agenata i A/B varijanti, ugrađene izlazne konfiguracije i konfiguracije u stvarnom vremenu te upite vraćene putem konfiguracijskih webhookova. Nepoznati rezervirani dijelovi {{name}} postaju prazan tekst, čak i kada nisu navedene varijable variables. Provjerite postojeće upite prije uvođenja, uključujući ugrađene upite i upite webhookova dostavljene iz vanjskih izvora koje ThunderPhone ne može evidentirati. Pozivi mikrofona u alatu Builder i simulacijski pozivi primjenjuju isto zadano ponašanje za prazne vrijednosti.