---
title: "Premenné a kontext pre jednotlivé hovory"
description: "Poskytnite každému hovoru vlastné údaje ako pomenované premenné pre prompt alebo stručné zadanie vo voľnom formáte bez zmeny agenta."
---

Každý hovor môže obsahovať dva typy vstupu pre konkrétny hovor. Použite jeden z nich alebo oba
spoločne:

- **`variables`**: pomenované hodnoty, ktoré vyplnia `{{placeholders}}` v prompte. Použite
  ich pre polia, na ktoré sa prompt odkazuje podľa názvu, napríklad meno volajúceho,
  číslo účtu alebo termín stretnutia.
- **`context`**: voľný text pridaný za prompt. Použite ho pre zadanie, ktoré
  sa nezmestí do šablóny, napríklad opis úlohy pre tento hovor alebo
  poznámky zhromaždené skôr.

Oba fungujú s uloženým agentom aj s vloženou konfiguráciou pri každom spôsobe
spustenia hovoru opísanom nižšie. Ani jeden nemení uloženého agenta, jeho históriu
verzií ani ostatné nastavenia.

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

## Premenné

Do výzvy uloženého agenta vložte zástupné symboly a pri spustení hovoru potom zadajte objekt `variables`. ThunderPhone vykreslí text pred odoslaním konfigurácie hovoru do hlasového runtime.

Ak nie sú potrebné žiadne hodnoty, `variables` vynechajte, neposielajte `null` (odmietnuté s `400`).

### Zástupné premenné a predvolené hodnoty

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

Názvy rozlišujú veľkosť písmen a riadia sa vzorom `[A-Za-z_][A-Za-z0-9_]*`. Medzery okolo
názvu sú povolené; medzery za znakom `|` sú súčasťou predvolenej hodnoty a
zachovajú sa. `{{name|Friend}}` použije `Friend`, keď `name` chýba alebo má hodnotu
`null`; prázdny reťazec je explicitne zadaná hodnota. Chýbajúce hodnoty bez
predvolenej hodnoty sa zmenia na prázdne reťazce a ich názvy sa zobrazia v `unresolved_variables`.
Text medzi dvojitými zloženými zátvorkami, ktorý nie je platným zástupným symbolom, sa odstráni. Text v dvojitých zložených
zátvorkách v každej zadanej hodnote sa odstraňuje nezávisle; hodnota nemôže odstrániť
okolité texty výzvy ani inú hodnotu. Odstránia sa aj nespárované oddeľovače dvojitých zložených zátvoriek.
Príklady JSON vo výzvach nesmú používať `{{`.
Hodnoty sú obyčajný text a nikdy sa nevyhodnocujú
ako kód ani sa rekurzívne nerozbaľujú ako šablóny.

Premenné sa môžu zobrazovať aj vo výzvach na potvrdenie, v odchádzajúcich hlasových správach
a v texte oznámenia o súhlase, keď sa toto pole odosiela pre
telefónny hovor. Agent nemá samostatné pole `first_message`: úvodné pokyny vložte do výzvy. Existujúce zástupné symboly hlasovej správy `{agent_name}` a `{org_name}`
naďalej fungujú.

### Hodnoty a limity

Hodnoty môžu byť reťazce, čísla, booleovské hodnoty alebo `null`; booleovské hodnoty sa vykresľujú ako `true`
a `false`. Riadiace znaky Unicode (`Cc`) s výnimkou nového riadka (`\n`), tabulátora (`\t`)
a návratu vozíka (`\r`), formátovacie znaky (`Cf`) s výnimkou spojovníka
a spojovača s nulovou šírkou (U+200C, U+200D, ktoré tvoria slová v jazykoch s indickým
a arabským písmom) a kódové body náhradných znakov (`Cs`) sa odstránia; `\r\n`
sa normalizuje na `\n`. Každá hodnota
je pri vykreslení obmedzená na 2 000 znakov. Dodané reťazce sa pred uložením tiež vyčistia a
skrátiia. Pôvodný objekt musí mať maximálne **32 KB JSON v UTF-8**; väčšie objekty dostanú
`400` v požiadavkách na hovory alebo relácie, zatiaľ čo importy kampaní nahlásia neplatné riadky samostatne. Polia a vnorené objekty nie sú
ako hodnoty prijímané. Nezhodné kľúče metadát (napríklad hlavička CSV s
medzerou) sa zachovajú a vrátia, ale nemožno na ne odkazovať pomocou zástupného symbolu.

## Kontext

`context` je reťazec s dĺžkou najviac **20 000 znakov**. ThunderPhone ho pridá za
prompt po doplnení premenných promptu ako oddelený 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 ho číta spolu so svojimi pokynmi, preto ho napíšte tak, ako by ste
pred hovorom informovali kolegu. Kontext nie je šablóna:
`{{name}}` v ňom zostane napísané tak, ako je. Ak text potrebuje hodnotu, vložte ju
sami pred odoslaním.

- `null`, prázdny reťazec alebo iba medzery znamenajú, že kontext nie je k dispozícii.
- Hodnota, ktorá nie je reťazec alebo je dlhšia než 20 000 znakov, sa pri požiadavkách na hovor a reláciu odmietne s kódom `400`; z konfiguračného webhooku zlyhá výmena rovnako ako pri neplatných `variables` (pozrite nižšie).
- Úvodné a koncové medzery sa odstránia a odstránia sa aj rovnaké riadiace a formátovacie znaky ako pri hodnotách premenných.
- Kontext je súčasťou výzvy hovoru, takže sa započítava do [veľkosti výzvy](/sk/guides/pricing).

Pri agentovi s [krokmi](/sk/guides/agent-steps) nasleduje kontext za promptom
každého agenta v hovore, nie za pokynmi jednotlivých krokov.

## Odkiaľ pochádzajú hodnoty

### Odchádzajúce API

Odošlite `variables` a `context` v požiadavke `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."
}
```

Obe možnosti fungujú aj s predvoleným odchádzajúcim agentom telefónneho čísla alebo s vloženým `config.prompt`. Pri vloženej konfigurácii môže byť `context` aj v rámci `config`, teda v rovnakom poli, aké vracia konfiguračný webhook; ak odošlete obe, musia obsahovať rovnaký text. Kľúč idempotencie nemožno znovu použiť s odlišnými premennými alebo odlišným kontextom.

### CSV kampane

Stĺpce CSV iné než telefónne číslo sa už ukladajú ako premenné kontaktu. Každé volanie ich teraz používa automaticky. Použite hlavičky ako `name`, `account_id` a `appointment_slot`, aby zodpovedali vašim zástupným symbolom. Existujúce mapovanie mena môže skombinovať stĺpce s menom a priezviskom do premennej `name`. Kontakty kampane nemajú kontext pre jednotlivé kontakty.

### Webhook dynamickej konfigurácie

V ceste webhooku blokujúcej konfigurácie vráťte uloženého agenta vo svojej organizácii spolu s ľubovoľnými hodnotami pre konkrétny hovor. Pri agentovi Full duplex si hovor zachová hlas agenta aj vtedy, keď sa začne v inom podporovanom jazyku: mapovania hlasov podľa jazyka a natívne prepínanie hlasov sa na tento hovor nevzťahujú.

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

Premenné v odpovedi prepíšu premenné na úrovni požiadavky, ostatné kľúče požiadavky však zostanú zachované. Hodnota odpovede `null` vyberie predvolenú hodnotu zástupného prvku.
Zlúčený objekt sa tiež musí zmestiť do 32 KB. Odpovede uloženého agenta prijímajú iba
`agent_id`, `variables`, `context`, `language` a časové pásmo pre jednotlivý hovor
[`timezone`](/sk/guides/dynamic-call-config); ak potrebujete
nahradiť výzvu alebo iné nastavenia, vráťte vloženú konfiguráciu. Odpovede webhooku
uloženého agenta používajú nasadené A/B rozdelenie agenta pri telefonických hovoroch aj hovoroch vo widgete;
premenné sa vyhodnotia po výbere variantu. Keď odpoveď nastaví `language` pre
agenta, ktorý nepoužíva Full duplex, hovor použije aj hlas daného jazyka, ak ho
preň agent má nastavený. Odpoveď obsahujúca `prompt` vždy používa vloženú
konfiguráciu: každý `agent_id` v tejto odpovedi sa ignoruje vrátane hodnoty null alebo
neceločíselných metadát. Vložená výzva musí stále prejsť bežnou validáciou.
Vložené odpovede webhooku môžu obsahovať aj `variables` a `context`. Hodnota `context`,
ktorá nie je reťazcom alebo je príliš dlhá, spôsobí zlyhanie výmeny: telefonický hovor sa
odmietne a požiadavka na reláciu widgetu zlyhá s kódom `400`. Odpovede webhooku
uloženého agenta používajú nasadené A/B rozdelenie agenta pri telefonických hovoroch aj hovoroch vo widgete;
premenné sa vyhodnotia po výbere variantu. Pri prichádzajúcich telefonických hovoroch použite číslo bez priradeného prichádzajúceho
agenta a nakonfigurujte webhook jeho telefónneho čísla alebo organizácie; kľúče widgetu používajú
`mode="webhook"`. Prichádzajúce oznámenia systému endpointov neposkytujú blokujúce
odpovede konfigurácie.

### Webhook nastavenia hovoru agenta

Ak chcete ponechať číslo priradené k hlasovému agentovi a vyplniť iba hodnoty hovoru,
priraďte hlasovému agentovi [webhook nastavenia hovoru](/sk/webhooks/call-incoming).
Pred každým prichádzajúcim hovorom, ktorý hlasový agent prijme na čísle, webhook dostane
hovor a ID, názov a verziu hlasového agenta a odpovie rovnakými hodnotami
`variables`, `context`, `language` a časového pásma `timezone` pre konkrétny hovor ako vyššie, bez potreby `agent_id`. Hlasový agent,
ktorého nastavenia používajú zástupný symbol bez predvolenej hodnoty, potrebuje tento webhook na prijatie
hovoru na telefónne číslo: ak webhook zlyhá, hovor sa nezačne. Zástupné symboly s predvolenou hodnotou,
napríklad `{{name|there}}`, umožňujú hlasovému agentovi prijať hovor aj bez neho.

### Hlavičky SIP

Hovory, ktoré sa k agentovi dostanú cez SIP (na [adrese SIP](/sk/guides/sip-addresses) alebo
na čísle pri manuálnom pripojení SIP), môžu prenášať kontext v hlavičkách `X-*` a
`User-to-User`. Každá z nich sa zmení na premennú `sip_`, napríklad
`{{sip_x_amzn_connectcontactid}}` alebo `{{sip_uui}}`, s najnižšou
prioritou: prednosť má hodnota s rovnakým názvom z API alebo webhooku. Pozrite si
[Odovzdanie kontextu hovoru v hlavičkách SIP](/sk/guides/sip-addresses).
Hodnoty hlavičiek nastavuje odosielateľ, preto ich považujte za nedôveryhodné, rovnako ako každú
hodnotu poskytnutú prehliadačom.

### API relácie widgetu

`POST /v1/widget/session` prijíma `variables` a `language` na najvyššej úrovni. Jeho publikovateľný
kľúč vyberá uloženého agenta. Kľúče v režime webhooku posielajú tieto hodnoty do
konfiguračného webhooku a zlúčia odpoveď podľa vyššie uvedeného popisu.
`variables` widgetu dodané prehliadačom riadi klient, po overení a vyčistení reťazcov opísaných
vyššie sa doslovne posielajú ďalej v `web.incoming` a odrážajú sa vo webhookoch po dokončení
a v histórii hovorov. Nepovažujte ich za dôveryhodné údaje o identite ani autorizácii.

Vlastné pole `context` widgetu v prehliadači je odlišné: prenáša text zo
stránky, na ktorej sa návštevník nachádza a ktorý agent považuje za obsah webovej stránky (pozrite
[Vloženie webového widgetu](/sk/guides/embed-web-widget)). Kontext widgetového hovoru pre konkrétny hovor
pochádza z konfiguračného webhooku kľúča v režime webhooku, ako je uvedené vyššie. Ak má
hovor oboje, najprv sa použije kontext pre konkrétny hovor a potom obsah stránky.

### API relácie v reálnom čase

`POST /v1/realtime/sessions` prijíma `variables`, `context` a `language` na najvyššej úrovni spolu s `agent_id` alebo vloženou konfiguráciou `config`:

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

`context` patrí iba na najvyššiu úroveň; vložený `config` ho odmietne ako
neznáme pole.

### Realtime WebSocket

Pri uloženom agentovi zostáva nasadený prompt uloženého agenta jeho promptom.
`session.instructions` sa stáva kontextom hovoru, `session.prompt.variables`
(alebo `session.config.variables`) sa stávajú jeho premennými a `session.language`
sa stáva jeho jazykom pre daný hovor. Agenta vyberte pomocou
`session.prompt.id` v prvej aktualizácii `session.update`, ktorá spustí reláciu po
doručení tejto aktualizácie:

```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 adrese URL pripojenia spustí agenta hneď po pripojení socketu,
pred akýmkoľvek `session.update`, takže neprenáša žiadne vstupy pre konkrétny hovor. Pridajte
`&wait_for_session_update=1`, aby sa počkalo na prvú správu `session.update` a použili sa jej
inštrukcie a premenné.

V inline relácii (bez uloženého agenta) je `session.instructions` samotný prompt,
rovnako ako predtým. Testovacie hovory cez mikrofón v nástroji Builder a simulované hovory vyriešia predvolené hodnoty a
chýbajúce zástupné symboly, no nemajú premenné ani vstup kontextu pre konkrétny hovor.

## Po hovore

`GET /v1/calls`, `GET /v1/calls/{call_id}`, `telephony.complete` a `web.complete` obsahujú
konečné zlúčené `variables` a `unresolved_variables`. Staršie dátové štruktúry dokončenia,
ktoré obsahujú `data.history`, ich obsahujú tiež:

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

`prompt_snapshot` hovoru (`GET /v1/calls/{call_id}`) zobrazuje výzvu agenta
s vyplnenými premennými a pridaným blokom kontextu.

Uložte identifikátor CRM alebo úlohy do objektu premenných, aby ste dokončený
hovor prepojili späť so zdrojovým záznamom. Premenné a kontext sa uchovávajú so
záznamom hovoru; odosielajte iba informácie, ktoré je vhodné uchovávať v
histórii hovorov a webhookoch.

Prehrania hovoru v [validačných sadách](/api-reference/validation-sets),
[spusteniach prehrávania](/api-reference/replay-runs) a
[vyšetrovaniach](/api-reference/investigations) používajú premenné a kontext
daného hovoru spolu s testovanou výzvou, takže prehranie testuje, čo by bolo
agentovi v danom hovore povedané.

## Kompatibilita existujúcich promptov

Vykresľovanie sa vzťahuje aj na existujúce prompty uložených agentov a variantov A/B, vložené odchádzajúce konfigurácie a konfigurácie v reálnom čase, ako aj na prompty vrátené konfiguračnými webhookmi. Neznáme zástupné symboly `{{name}}` sa zmenia na prázdny text, aj keď nie sú poskytnuté žiadne `variables`. Pred nasadením skontrolujte existujúce prompty vrátane externe dodávaných vložených promptov a promptov webhookov, ktoré ThunderPhone nedokáže evidovať. Volania mikrofónu v nástroji Builder a simulačné volania používajú rovnaké predvolené správanie so zadanou hodnotou alebo prázdnym textom.
