--- title: "Kõnepõhised muutujad ja kontekst" description: "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. ```json { "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 ```text 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: ```text Details for this call: Ada rescheduled twice last month. She prefers mornings and asked us not to call her work number. ``` 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](/et/guides/pricing) hulka. [Etappidega](/et/guides/agent-steps) 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`: ```json { "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: ```json { "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`](/et/guides/dynamic-call-config); 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](/et/webhooks/call-incoming). 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](/et/guides/sip-addresses) 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](/et/guides/sip-addresses). 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](/et/guides/embed-web-widget)). 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: ```json { "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: ```json { "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: ```json { "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](/api-reference/validation-sets), [taasesituskäikudes](/api-reference/replay-runs) ja [uurimistes](/api-reference/investigations) 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.