---
title: "Spremenljivke in kontekst za posamezen klic"
description: "Vsakemu klicu dodajte lastne podrobnosti kot poimenovane spremenljivke za poziv ali kratko besedilo proste oblike, ne da bi spremenili agenta."
---

Vsak klic lahko vsebuje dve vrsti vnosa za posamezen klic. Uporabite eno ali
obe skupaj:

- **`variables`**: poimenovane vrednosti, ki v pozivu izpolnijo `{{placeholders}}`. Uporabite
  jih za polja, na katera se poziv sklicuje po imenu, na primer ime klicatelja,
  številko računa ali termin sestanka.
- **`context`**: besedilo proste oblike, dodano za pozivom. Uporabite ga za povzetek, ki
  ne ustreza predlogi, na primer opis naloge za ta klic ali prej zbrane
  opombe.

Obe možnosti delujeta s shranjenim agentom in z vstavljeno konfiguracijo pri vseh
spodaj opisanih načinih za začetek klica. Nobena ne spremeni shranjenega agenta,
njegove zgodovine različic ali drugih nastavitev.

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

## Spremenljivke

V poziv shranjenega agenta vstavite označbe mest, nato pa ob začetku klica posredujte objekt `variables`. ThunderPhone besedilo upodobi, preden konfiguracijo klica pošlje v izvajalno okolje glasovnega agenta.

Kadar vrednosti niso potrebne, `variables` izpustite in ne pošiljajte `null` (zahteva je zavrnjena s `400`).

### Nadomestne spremenljivke in privzete vrednosti

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

Imena razlikujejo med velikimi in malimi črkami ter sledijo vzorcu `[A-Za-z_][A-Za-z0-9_]*`. Presledki okoli
imena so dovoljeni; presledki za `|` so del privzete vrednosti in se
ohranijo. `{{name|Friend}}` uporabi `Friend`, kadar `name` manjka ali je
`null`; prazen niz je izrecno posredovana vrednost. Manjkajoče vrednosti brez
privzete vrednosti postanejo prazni nizi, njihova imena pa se prikažejo v `unresolved_variables`.
Besedilo med dvojnimi zavitimi oklepaji, ki ni veljavna ograda, se odstrani. Besedilo v dvojnih zavitih
oklepajih znotraj posamezne posredovane vrednosti se odstrani neodvisno; vrednost ne more odstraniti
okoliškega besedila poziva ali druge vrednosti. Odstranijo se tudi neusklajeni ločilniki z dvojnimi zavitimi oklepaji.
Primeri JSON v pozivih ne smejo uporabljati `{{`.
Vrednosti so navadno besedilo in se nikoli ne ovrednotijo
kot koda ali rekurzivno razširijo kot predloge.

Spremenljivke se lahko pojavijo tudi v pozivih za potrditev, odhodnih glasovnih sporočilih
in besedilu obvestila o soglasju, kadar je to polje poslano za
telefonski klic. Agent nima ločenega polja `first_message`: uvodna
navodila dodajte v poziv. Obstoječi ogradi za glasovno pošto `{agent_name}` in `{org_name}`
še naprej delujeta.

### Vrednosti in omejitve

Vrednosti so lahko nizi, števila, logične vrednosti ali `null`; logične vrednosti se izpišejo kot `true`
in `false`. Nadzorni znaki Unicode (`Cc`) razen nove vrstice (`\n`), tabulatorja (`\t`)
in povratka nosilca (`\r`), znaki oblikovanja (`Cf`) razen ničširinskega
nezdruževalnika in združevalnika (U+200C, U+200D, ki zapisujeta besede v indijskih
jezikih in jezikih z arabsko pisavo) ter kodne točke nadomestkov (`Cs`) so odstranjeni; `\r\n`
se normalizira v `\n`. Vsaka vrednost
je ob izpisu omejena na 2.000 znakov. Posredovani nizi se pred shranjevanjem prav tako očistijo in
okrajšajo. Izvirni objekt mora ustrezati omejitvi **32 KB JSON-a UTF-8**; večji objekti prejmejo `400`
pri zahtevah za klic/sejo, medtem ko uvozi kampanj posamezno poročajo o neveljavnih vrsticah. Polja in ugnezdeni objekti niso
sprejeti kot vrednosti. Metapodatkovni ključi, ki ne ustrezajo zahtevam (na primer glava CSV s
presledkom), se ohranijo in vrnejo, vendar jih ni mogoče uporabiti v nadomestnem označevalniku.

## Kontekst

`context` je niz z največ **20.000 znaki**. ThunderPhone ga doda za
poziv, ko so spremenljivke poziva zapolnjene, kot razmejen blok:

```text
<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 prebere skupaj z navodili, zato ga napišite tako, kot bi pred klicem
poučili sodelavca. Kontekst ni predloga:
`{{name}}` v njem ostane zapisan tako, kot je. Če besedilo potrebuje vrednost, jo
vstavite sami pred pošiljanjem.

- `null`, prazen niz ali samo presledki pomenijo, da ni konteksta.
- Vrednost, ki ni niz ali je daljša od 20.000 znakov, je pri zahtevah za klic in sejo zavrnjena s kodo `400`; iz konfiguracijskega webhooka izmenjava ne uspe enako kot pri neveljavnih `variables` (glejte spodaj).
- Vodilni in končni presledki so odstranjeni, prav tako pa so odstranjeni enaki nadzorni in oblikovni znaki kot pri vrednostih spremenljivk.
- Kontekst je del poziva klica, zato se všteva v [velikost poziva](/sl/guides/pricing) klica.

Pri agentu s [koraki](/sl/guides/agent-steps) kontekst sledi pozivu
vsakega agenta v klicu, ne navodilom posameznega koraka.

## Od kod prihajajo vrednosti

### Odhodni API

Pošljite `variables` in `context` v `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."
}
```

Oboje deluje tudi s privzetim odhodnim agentom telefonske številke ali z vdelanim
`config.prompt`. Pri vdelani konfiguraciji je lahko `context` tudi znotraj `config`,
v istem polju, ki ga vrne konfiguracijski webhook; če pošljete oboje, mora biti
besedilo enako. Ključa za idempotentnost ni mogoče znova uporabiti z drugačnimi spremenljivkami ali drugačnim kontekstom.

### CSV kampanje

Stolpci CSV, ki niso telefonske številke, so že shranjeni kot spremenljivke stika. Vsako klicanje jih zdaj uporablja samodejno. Za ujemanje z vašimi ogradami uporabite glave, kot so `name`, `account_id` in `appointment_slot`. Obstoječe preslikavanje imen lahko združi stolpca z imenom in priimkom v spremenljivko `name`. Stiki v kampanji nimajo konteksta za posamezen stik.

### Spletni kavelj za dinamično konfiguracijo

Na poti blokirajočega webhooka za konfiguracijo vrnite shranjenega agenta v svoji organizaciji skupaj z vsemi vrednostmi za posamezen klic. Pri agentu Full duplex klic ohrani glas agenta tudi, če se začne v drugem podprtem jeziku: preslikave glasov po jezikih in izvorno preklapljanje glasov se za ta klic ne uporabljajo.

```json
{
  "agent_id": 12,
  "variables": {"name": "Ada", "account_id": "A-17"},
  "context": "[REDACTED_LITERAL]"
}
```

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

Spremenljivke iz odgovora prepišejo spremenljivke na ravni zahteve, drugi ključi
zahteve pa ostanejo. Vrednost `null` v odgovoru izbere privzeto vrednost nadomestnega mesta.
Tudi združeni objekt mora biti velik največ 32 KB. Odgovori shranjenega agenta sprejemajo le
`agent_id`, `variables`, `context`, `language` in časovni pas za posamezen klic
[`timezone`](/sl/guides/dynamic-call-config); kadar morate
zamenjati poziv ali druge nastavitve, vrnite vdelano konfiguracijo. Odgovori webhooka
shranjenega agenta uporabljajo uvedeno razdelitev A/B agenta za klice prek telefona in pripomočka;
spremenljivke se izrišejo po izbiri različice. Ko odgovor nastavi `language` za
agenta, ki ni Full duplex, klic uporabi tudi lasten glas tega jezika, če ga
ima agent nastavljenega zanj. Odgovor, ki vsebuje `prompt`, vedno uporablja vdelano
konfiguracijo: vsak `agent_id` v tem odgovoru se prezre, vključno z metapodatki null ali
necelimi števili. Vdelani poziv mora še vedno uspešno prestati običajno preverjanje veljavnosti.
Vdelani odgovori webhooka lahko vključujejo tudi `variables` in `context`. `context`,
ki ni niz ali je predolg, povzroči neuspeh izmenjave: telefonski klic je
zavrnjen, zahteva za sejo pripomočka pa ne uspe s kodo `400`. Odgovori webhooka
shranjenega agenta uporabljajo uvedeno razdelitev A/B agenta za klice prek telefona in pripomočka;
spremenljivke se izrišejo po izbiri različice. Pri dohodnih telefonskih klicih uporabite številko brez dodeljenega dohodnega
agenta in konfigurirajte webhook telefonske številke ali organizacije; ključi pripomočka uporabljajo
`mode="webhook"`. Dohodna obvestila sistema končnih točk ne zagotavljajo blokirajočih
konfiguracijskih odgovorov.

### Spletna kljuka za nastavitev klica agenta

Če želite številko ohraniti dodeljeno njenemu agentu in izpolniti samo vrednosti klica, agentu dodajte [spletni kavelj za nastavitev klica](/sl/webhooks/call-incoming).
Pred vsakim dohodnim klicem, na katerega agent odgovori na številki, spletni kavelj prejme klic ter ID, ime in različico agenta ter odgovori z enakimi vrednostmi `variables`, `context`, `language` in `timezone` za posamezen klic kot zgoraj, ne da bi potreboval `agent_id`. Agent, katerega nastavitve uporabljajo ogrado brez privzete vrednosti, potrebuje ta spletni kavelj za odgovor na telefonsko številko: klic se ne začne, če spletni kavelj ne uspe. Ograde s privzeto vrednostjo, kot je `{{name|there}}`, agentu omogočajo odgovor tudi brez njega.

### Glave SIP

Klici, ki dosežejo agenta prek SIP (prek [naslova SIP](/sl/guides/sip-addresses) ali
številke pri ročni povezavi SIP), lahko nosijo kontekst v glavah `X-*` in
`User-to-User`. Vsaka postane spremenljivka `sip_`, kot sta
`{{sip_x_amzn_connectcontactid}}` ali `{{sip_uui}}`, z najnižjo
prednostjo: vrednost z enakim imenom iz API-ja ali webhooka ima prednost. Oglejte si
[Posredovanje konteksta klica v glavah SIP](/sl/guides/sip-addresses).
Vrednosti glav nastavi pošiljatelj, zato jih obravnavajte kot nezaupanja vredne,
tako kot katero koli vrednost, ki jo posreduje brskalnik.

### API seje pripomočka

`POST /v1/widget/session` sprejema `variables` in `language` na najvišji ravni. Njegov objavljivi
ključ izbere shranjenega agenta. Ključi v načinu webhook te vrednosti posredujejo
konfiguracijskemu webhooku in odgovor združijo, kot je opisano zgoraj.
`variables` gradnika, ki jih posreduje brskalnik, nadzoruje odjemalec in se
dobesedno posredujejo v `web.incoming` po zgoraj opisanem preverjanju in
čiščenju nizov ter odražajo v webhookih ob zaključku in zgodovini klicev. Ne obravnavajte jih
kot zaupanja vredne podatke za identifikacijo ali avtorizacijo.

Lastno polje `context` pripomočka v brskalniku je drugačno: prenaša besedilo s
strani, ki jo obiskovalec gleda in ki jo agent obravnava kot vsebino spletnega mesta (glejte
[Vdelajte spletni pripomoček](/sl/guides/embed-web-widget)). Kontekst posameznega klica pripomočka
prihaja iz konfiguracijskega spletnega kavlja ključa v načinu spletnega kavlja, kot je opisano zgoraj. Kadar ima
klic oba, je najprej kontekst posameznega klica, nato vsebina strani.

### API seje v realnem času

`POST /v1/realtime/sessions` sprejema `variables`, `context` in `language` na najvišji ravni
skupaj z `agent_id` ali vdelano konfiguracijo `config`:

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

`context` je dovoljen samo na najvišji ravni; vdelana `config` ga zavrne kot
neznano polje.

### Realtime WebSocket

S shranjenim agentom uvedeni poziv shranjenega agenta ostane njegov poziv.
`session.instructions` postane kontekst klica, `session.prompt.variables`
(ali `session.config.variables`) postanejo njegove spremenljivke, `session.language`
pa postane jezik posameznega klica. Agenta izberite s
`session.prompt.id` v prvi posodobitvi `session.update`, ki zažene sejo, ko
prispe ta posodobitev:

```json
{
  "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` v URL-ju povezave zažene agenta takoj, ko se vtičnica
poveže, še pred katerim koli `session.update`, zato ne vsebuje vnosa za posamezni klic. Dodajte
`&wait_for_session_update=1`, da počakate na prvi `session.update` in uporabite njegova
navodila in spremenljivke.

V vdelani seji (brez shranjenega agenta) je `session.instructions` sam poziv,
kot prej. Klici s mikrofonom v gradniku in simulirani preskusni klici razrešijo privzete vrednosti in
manjkajoče označbe mest, vendar nimajo spremenljivk ali vnosa konteksta za posamezni klic.

## Po klicu

`GET /v1/calls`, `GET /v1/calls/{call_id}`, `telephony.complete` in `web.complete` vključujejo končne
združene `variables` in `unresolved_variables`. Podedovane koristne vsebine ob zaključku,
ki vključujejo `data.history`, jih prav tako vključujejo:

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

`prompt_snapshot` klica (`GET /v1/calls/{call_id}`) prikazuje poziv agenta z
izpolnjenimi spremenljivkami in dodanim blokom konteksta.

Identifikator CRM-ja ali opravila shranite v objekt spremenljivk, da dokončani
klic povežete nazaj z izvornim zapisom. Spremenljivke in kontekst se ohranijo z
zapisom klica; pošiljajte le informacije, ki jih je primerno hraniti v zgodovini
klicev in spletnih kavljih.

Ponovitve klica v [naborih za preverjanje](/api-reference/validation-sets),
[izvajanjih ponovitev](/api-reference/replay-runs) in
[preiskavah](/api-reference/investigations) uporabljajo spremenljivke in
kontekst tega klica s pozivom, ki se preskuša, zato ponovitev preveri, kaj bi
bilo agentu v tem klicu sporočeno.

## Združljivost z obstoječimi pozivi

Upodabljanje velja tudi za obstoječe pozive shranjenih agentov in različic A/B, vstavljene odhodne konfiguracije in konfiguracije v realnem času ter pozive, vrnjene prek spletnih kljuk konfiguracije. Neznani označevalniki `{{name}}` postanejo prazno besedilo, tudi če niso navedene nobene spremenljivke `variables`. Pred uvedbo preverite obstoječe pozive, vključno z zunanje posredovanimi vstavljenimi pozivi in pozivi prek spletnih kljuk, ki jih ThunderPhone ne more evidentirati. Klici z mikrofonom v gradniku in simulacijski klici uporabljajo enako privzeto/prazno vedenje.
