ThunderPhone 2.0 on nüüd saadaval.Iseteenindusena alates 2 senti/min.Loe uudist
Alusta

Developer cookbook

View as Markdown
Open in
ClaudeChatGPTCursor

Kõnepõhised muutujad ja kontekst

Anna igale kõnele oma üksikasjad nimega muutujatena viiba jaoks või vabavormilise lühikirjeldusena, ilma agenti muutmata.

Iga kõne võib sisaldada kahte tüüpi kõnepõhist sisendit. Kasuta üht neist või mõlemat koos:

  • variables: nimega väärtused, mis täidavad viibas olevad {{placeholders}}. Kasuta neid väljade jaoks, millele viip viitab nime järgi, näiteks helistaja nimi, kontonumber või kohtumise aeg.
  • context: vabavormiline tekst, mis lisatakse viiba järele. Kasuta seda lühikese ülevaate jaoks, mis ei sobi malli, näiteks selle kõne ülesande kirjelduse või varem kogutud märkmete jaoks.

Mõlemad töötavad salvestatud agendi ja sisekonfiguratsiooniga kõigil allpool kirjeldatud kõne alustamise viisidel. Kumbki ei muuda salvestatud agenti, selle versiooniajalugu ega muid seadeid.

{
  "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."
}

Muutujad

Lisa kohatäited salvestatud agendi viibasse, seejärel edasta kõne alustamisel objekt variables. ThunderPhone renderdab teksti enne kõne konfiguratsiooni saatmist häältöötluskeskkonda.

Kui väärtusi pole vaja, jäta variables välja; ära saada null (lükatakse tagasi koodiga 400).

Kohatäited ja vaikeväärtused

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

Nimed on tõstutundlikud ja järgivad mustrit [A-Za-z_][A-Za-z0-9_]*. Nime ümber olevad tühikud on lubatud; tühik pärast märki | on vaikeväärtuse osa ja säilitatakse. {{name|Friend}} kasutab väärtust Friend, kui name puudub või on null; tühi string on selgesõnaliselt määratud väärtus. Ilma vaikeväärtuseta puuduvad väärtused muutuvad tühjadeks stringideks ja nende nimed kuvatakse väljal unresolved_variables. Topeltsulgude vahel olev tekst, mis ei ole kehtiv kohatäide, eemaldatakse. Iga määratud väärtuse sees olev topeltsulgudes tekst eemaldatakse iseseisvalt; väärtus ei saa eemaldada ümbritsevat viibateksti ega teist väärtust. Eemaldatakse ka paarita topeltsulgude eraldajad. Viipades olevates JSON-i näidetes ei tohi kasutada {{. Väärtused on lihttekst ja neid ei käivitata kunagi koodina ega laiendata rekursiivselt mallidena.

Muutujad võivad esineda ka kinnituse viipades, väljaminevates kõneposti sõnumites ja nõusolekuteate tekstis, kui see väli telefonikõne jaoks saadetakse. Häälagendil ei ole eraldi välja first_message: lisa selle avamisjuhised viipa. Olemasolevad kõneposti kohatäited {agent_name} ja {org_name} töötavad edasi.

Väärtused ja piirangud

Väärtused võivad olla stringid, arvud, tõeväärtused või null; tõeväärtused kuvatakse kujul true ja false. Unicode’i juhtmärgid (Cc), välja arvatud reavahetus (\n), tabeldusmärk (\t) ja käru tagastus (\r), vormindusmärgid (Cf), välja arvatud nullilaiusega mitteliitja ja liitja (U+200C, U+200D, mida kasutatakse sõnade kirjutamiseks india ja araabia kirjas keeltes), ning surrogaadi (Cs) koodipunktid eemaldatakse; \r\n normaliseeritakse kujule \n. Iga väärtus on kuvatuna piiratud 2 000 märgiga. Esitatud stringid puhastatakse ja kärbitakse ka enne salvestamist. Algne objekt peab mahtuma 32 KB UTF-8 JSON-i; suuremate objektide korral tagastatakse kõne- ja seansipäringutele 400, samas kui kampaaniaimportides raporteeritakse vigased read eraldi. Massiive ja pesastatud objekte ei aktsepteerita väärtustena. Mittevastavad metaandmete võtmed (näiteks tühikuga CSV-päis) säilitatakse ja tagastatakse, kuid neile ei saa kohatäite abil viidata.

Kontekst

context on kuni 20 000 märgi pikkune string. ThunderPhone lisab selle pärast prompt’i, kui prompt’i muutujad on täidetud, eraldatud plokina:

<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>

Häälagent loeb seda koos oma juhistega, seega kirjuta see nii, nagu annaksid kolleegile enne kõnet ülevaate. Kontekst ei ole mall: selles olev {{name}} jääb muutmata. Kui tekst vajab väärtust, lisa väärtus enne saatmist ise.

  • null, tühi string või ainult tühikud tähendab, et konteksti pole.
  • Väärtus, mis ei ole string või on pikem kui 20 000 märki, lükatakse kõne- ja seansipäringutes tagasi koodiga 400; konfiguratsiooni veebikonksu kaudu nurjub vahetus samamoodi nagu vigaste variables korral (vt allpool).
  • Algus- ja lõputühikud kärbitakse ning eemaldatakse samad juht- ja vormindusmärgid nagu muutujate väärtustest.
  • Kontekst on osa kõne viibast, seega arvestatakse seda kõne viiba suuruse hulka.

Etappidega häälagendi puhul järgneb kontekst kõnes iga häälagendi prompt’ile, mitte iga etapi juhistele.

Kust väärtused pärinevad

Väljamineva kõne API

Saada variables ja context päringuga 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."
}

Mõlemad töötavad ka telefoninumbri vaikimisi väljamineva häälagendiga või tekstisisese config.prompt-iga. Tekstisisese konfiguratsiooni puhul võib context olla ka config-i sees, samas väljas, mille tagastab konfiguratsiooni veebikonks; kui saadad mõlemad, peavad need olema sama tekst. Idempotentsusvõtit ei saa taaskasutada erinevate muutujate või erineva kontekstiga.

Kampaania CSV

Muud kui telefoninumber CSV veerud salvestatakse juba kontaktimuutujatena. Iga valimine kasutab neid nüüd automaatselt. Kasuta kohatäidetega sobitamiseks päiseid nagu name, account_id ja appointment_slot. Olemasolev nime vastendus saab ühendada ees- ja perekonnanime veerud muutujaks name. Kampaania kontaktidel puudub kontaktipõhine kontekst.

Dünaamilise konfiguratsiooni webhook

Blokeerival konfiguratsiooni webhooki teel tagasta oma organisatsiooni salvestatud agent koos kõnepõhiste väärtustega:

{
  "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."
}

Vastuse muutujad kirjutavad taotlusetaseme muutujad üle, samal ajal kui muud taotluse võtmed jäävad alles. Vastuse väärtus null valib kohatäite vaikeväärtuse. Ühendatud objekt peab samuti mahtuma 32 KB sisse. Salvestatud agendi vastused aktsepteerivad ainult agent_id, variables, context, language ja kõnepõhist timezone; tagasta sisemine konfiguratsioon, kui pead asendama viiba või muid sätteid. Vastus, mis sisaldab prompt, kasutab alati sisemist konfiguratsiooni: selles vastuses olevat agent_id eiratakse, sealhulgas nulli või mittetäisarvulisi metaandmeid. Sisemine viip peab siiski läbima tavapärase valideerimise. Sisemised webhooki vastused võivad samuti sisaldada variables ja context. context, mis ei ole string või on liiga pikk, nurjab andmevahetuse: telefonikõne lükatakse tagasi ja vidina seansi taotlus nurjub koodiga 400. Salvestatud agendi webhooki vastused kasutavad agendi juurutatud A/B jaotust nii telefoni- kui ka vidinakõnede puhul; muutujad renderdatakse pärast variandi valimist. Sissetulevate telefonikõnede puhul kasuta numbrit, millele pole määratud sissetulevat agenti, ja seadista selle telefoninumbri või organisatsiooni webhook; vidina võtmed kasutavad mode="webhook". Lõpp-punkti süsteemi sissetulevad teavitused ei paku blokeerivaid konfiguratsioonivastuseid.

Agendi kõne seadistamise webhook

Et number jääks määratuks oma agendile ja täidetaks ainult kõne väärtused, anna agendile kõne seadistamise veebikonks. Enne iga sissetulevat kõnet, millele agent numbril vastab, saab veebikonks kõne ning agendi ID, nime ja versiooni ning vastab samade eespool kirjeldatud variables, context, language ja kõnepõhise timezone väärtustega, ilma et vajaks agent_id. Agent, kelle seadetes kasutatakse vaikeväärtuseta kohatäitjat, vajab telefoninumbrile vastamiseks seda veebikonksu: veebikonksu nurjumisel kõne ei alga. Vaikeväärtusega kohatäitjad, näiteks {{name|there}}, võimaldavad agendil sellele vastata.

SIP-päised

SIP-i kaudu agendini jõudvad kõned ( SIP-aadressi või käsitsi seadistatud SIP-ühenduse numbri kaudu) võivad kanda konteksti X-* ja User-to-User päistes. Igaüks neist muutub sip_ muutujaks, näiteks {{sip_x_amzn_connectcontactid}} või {{sip_uui}}, millel on madalaim prioriteet: sama nimega väärtus API-st või webhookist on ülimuslik. Vaata Kõnekonteksti edastamine SIP-päistes. Päiste väärtused määrab saatja, seega käsitle neid ebausaldusväärsetena nagu mis tahes brauseri edastatud väärtust.

Vidina seansi API

POST /v1/widget/session aktsepteerib tipptaseme variables ja language väärtusi. Selle avalik võti valib salvestatud agendi. Veebikonksurežiimi võtmed edastavad need väärtused konfiguratsiooni veebikonksule ja ühendavad vastuse eespool kirjeldatud viisil. Brauseri kaudu edastatud vidina variables on kliendi kontrolli all, need edastatakse muutmata kujul web.incoming väärtuses pärast eespool kirjeldatud valideerimist ja stringide puhastamist ning kajastatakse lõpetamise veebikonksudes ja kõneajaloos. Ära käsitle neid usaldusväärsete identiteedi- või autoriseerimisandmetena.

Vidina enda brauseri väli context on erinev: see sisaldab teksti lehelt, mida külastaja parasjagu vaatab ning mida häälagent käsitleb veebisaidi sisuna (vt Veebividina manustamine). Vidinakõne kõnepõhine kontekst pärineb eespool kirjeldatud veebikonksurežiimi võtme konfiguratsiooni veebikonksust. Kui kõnel on mõlemad, tuleb kõigepealt kõnepõhine kontekst ja seejärel lehe sisu.

Reaalajas seansi API

POST /v1/realtime/sessions aktsepteerib tipptaseme variables, context ja language koos agent_id või sisemise config-iga:

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

context saab olla ainult tipptasemel; sisemine config lükkab selle tagasi tundmatu väljana.

Reaalajas WebSocket

Salvestatud agendiga jääb salvestatud agendi kasutusele võetud viip selle viibaks. session.instructions muutub kõne kontekstiks, session.prompt.variables (või session.config.variables) muutuvad selle muutujateks ja session.language muutub kõne keeleks. Vali agent esimese session.update-iga session.prompt.id abil; seanss käivitub, kui see värskendus saabub:

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

Ühenduse URL-is olev ?agent_id=12 käivitab agendi kohe, kui sokkel ühendub, enne mis tahes session.update-i, seega ei sisalda see kõnepõhist sisendit. Lisa &wait_for_session_update=1, et oodata esimest session.update-i ning kasutada selle juhiseid ja muutujaid.

Sisesessioonis (ilma salvestatud agendita) on session.instructions nagu varem viip ise. Builderi mikrofoni- ja simuleeritud testkõned lahendavad vaikeväärtused ja puuduvad kohatäited, kuid neil puuduvad kõnepõhised muutujad ja kontekstisisend.

Pärast kõnet

GET /v1/calls, GET /v1/calls/{call_id}, telephony.complete ja web.complete sisaldavad lõplikke ühendatud variables ja unresolved_variables. Pärand-lõpetamise koormad, mis sisaldavad data.history, sisaldavad neid samuti:

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

Kõne prompt_snapshot (GET /v1/calls/{call_id}) näitab agendi viipa, kus muutujate väärtused on täidetud ja kontekstiplokk lisatud.

Salvesta oma CRM-i või ülesande identifikaator muutujate objekti, et siduda lõpetatud kõne tagasi selle lähtekirjega. Muutujad ja kontekst säilitatakse koos kõnekirjega; saada ainult teavet, mida on sobilik säilitada kõneajaloos ja veebikonksudes.

Kõne taasesitused valideerimiskomplektides, taasesituskäikudes ja uurimistes kasutavad selle kõne muutujaid ja konteksti koos testitava viibaga, nii et taasesitus testib seda, mida selle kõne agendile oleks öeldud.

Ühilduvus olemasolevate promptidega

Renderdamist rakendatakse ka olemasolevatele salvestatud agentide ja A/B-variantide promptidele, reasisestele väljaminevatele ja reaalajas konfiguratsioonidele ning konfiguratsiooni veebikonksude tagastatud promptidele. Tundmatud {{name}} kohatäited muutuvad tühjaks tekstiks isegi siis, kui variables pole määratud. Kontrolli enne juurutamist olemasolevaid prompte, sealhulgas väliselt edastatud reasiseseid/veebikonksu prompte, mida ThunderPhone ei saa inventeerida. Builderi mikrofoni- ja simulatsioonikõnedes rakendatakse sama vaike-/tühikäitumist.