---
title: "Varijable i kontekst po pozivu"
description: "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.

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

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

```text
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:

```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 č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](/hr/guides/pricing).

Kod agenta s [koracima](/hr/guides/agent-steps), 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`:

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

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

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`](/hr/guides/dynamic-call-config); 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](/hr/webhooks/call-incoming).
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](/hr/guides/sip-addresses) 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](/hr/guides/sip-addresses).
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](/hr/guides/embed-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`:

```json
{
  "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:

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

```json
{
  "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](/api-reference/validation-sets),
[izvršavanjima repriza](/api-reference/replay-runs) i
[istragama](/api-reference/investigations), 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.
