---
title: "Proměnné a kontext pro jednotlivé hovory"
description: "Přidejte každému hovoru vlastní údaje jako pojmenované proměnné pro prompt nebo volně formulované zadání, aniž byste měnili agenta."
---

Každý hovor může obsahovat dva druhy vstupu pro konkrétní hovor. Použijte
jeden z nich nebo oba současně:

- **`variables`**: pojmenované hodnoty, které vyplní `{{placeholders}}` v promptu. Použijte je
  pro pole, na která se prompt odkazuje názvem, například jméno volajícího,
  číslo účtu nebo termín schůzky.
- **`context`**: volný text přidaný za prompt. Použijte jej pro stručné zadání, které
  se nevejde do šablony, například popis úkolu pro tento hovor nebo
  dříve shromážděné poznámky.

Oba fungují s uloženým agentem i s vloženou konfigurací při každém níže
popsaném způsobu zahájení hovoru. Ani jeden nemění uloženého agenta, jeho historii
verzí ani jeho další nastavení.

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

## Proměnné

Do výzvy uloženého agenta vložte zástupné symboly a při zahájení hovoru poté předejte objekt `variables`. ThunderPhone vykreslí text před odesláním konfigurace hovoru do hlasového modulu.

Pokud nejsou potřeba žádné hodnoty, `variables` vynechejte; neposílejte `null` (bude odmítnuto s `400`).

### Zástupné proměnné a výchozí hodnoty

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

Názvy rozlišují velikost písmen a řídí se vzorem `[A-Za-z_][A-Za-z0-9_]*`. Mezery kolem názvu jsou povoleny; mezery za `|` jsou součástí výchozí hodnoty a zachovají se. `{{name|Friend}}` použije `Friend`, pokud `name` chybí nebo má hodnotu `null`; prázdný řetězec je výslovně dodaná hodnota. Chybějící hodnoty bez výchozí hodnoty se změní na prázdné řetězce a jejich názvy se zobrazí v `unresolved_variables`. Text mezi dvojitými složenými závorkami, který není platným zástupným symbolem, se odstraní. Text v dvojitých složených závorkách uvnitř každé dodané hodnoty se odstraňuje nezávisle; hodnota nemůže odstranit okolní text promptu ani jinou hodnotu. Odstraní se také nespárované oddělovače dvojitých složených závorek. Příklady JSON v promptech nesmí používat `{{`. Hodnoty jsou prostý text, nikdy se nevyhodnocují jako kód ani se rekurzivně nerozbalují jako šablony.

Proměnné se mohou objevit také v promptech potvrzení, odchozích hlasových zprávách a textu oznámení o souhlasu, pokud je toto pole odesláno pro telefonní hovor. Agent nemá samostatné pole `first_message`: jeho úvodní pokyny vložte do promptu. Stávající zástupné symboly hlasové schránky `{agent_name}` a `{org_name}` nadále fungují.

### Hodnoty a limity

Hodnoty mohou být řetězce, čísla, booleovské hodnoty nebo `null`; booleovské hodnoty se vykreslují jako `true`
a `false`. Řídicí znaky Unicode (`Cc`) s výjimkou nového řádku (`\n`), tabulátoru (`\t`)
a návratu vozíku (`\r`), formátovací znaky (`Cf`) s výjimkou spojovníku bez šířky a spojovače (U+200C, U+200D, které tvoří slova v indických jazycích a jazycích psaných
arabským písmem) a body kódu náhradních znaků (`Cs`) jsou odstraněny; `\r\n`
se normalizuje na `\n`. Každá hodnota
je při vykreslení omezena na 2 000 znaků. Dodané řetězce se před uložením také vyčistí a
zkrátí. Původní objekt musí být v rámci **32 KB JSON v UTF-8**; větší objekty obdrží `400`
v požadavcích na volání nebo relaci, zatímco importy kampaní jednotlivě hlásí neplatné řádky. Pole a vnořené objekty nejsou
jako hodnoty přijímány. Neodpovídající klíče metadat (například hlavička CSV s
mezerou) jsou zachovány a vráceny, ale nelze na ně odkazovat pomocí zástupného symbolu.

## Kontext

`context` je řetězec o délce až **20 000 znaků**. ThunderPhone jej přidá za
prompt poté, co jsou vyplněny proměnné promptu, jako oddělený 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 jej čte společně se svými pokyny, proto jej napište tak, jak byste před
voláním informovali kolegu. Kontext není šablona:
`{{name}}` v něm zůstává tak, jak je napsáno. Pokud text potřebuje hodnotu, doplňte ji
sami před odesláním.

- `null`, prázdný řetězec nebo pouze bílé znaky znamenají, že není k dispozici žádný kontext.
- Hodnota, která není řetězcem nebo je delší než 20 000 znaků, je při požadavcích na volání a relace odmítnuta s kódem `400`; z konfiguračního webhooku způsobí selhání výměny stejně jako neplatné `variables` (viz níže).
- Úvodní a koncové bílé znaky jsou oříznuty a jsou odstraněny stejné řídicí a formátovací znaky jako v hodnotách proměnných.
- Kontext je součástí promptu hovoru, takže se započítává do [velikosti promptu](/cs/guides/pricing).

U agenta s [kroky](/cs/guides/agent-steps) následuje kontext za promptem
každého agenta ve volání, nikoli za pokyny jednotlivých kroků.

## Odkud hodnoty pocházejí

### Odchozí API

Odešlete `variables` a `context` v požadavku `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."
}
```

Obojí funguje také s výchozím odchozím agentem telefonního čísla nebo s vloženým
`config.prompt`. Při použití vložené konfigurace může být `context` také uvnitř `config`,
tedy ve stejném poli, které vrací webhook konfigurace; pokud odešlete obojí, musí obsahovat
stejný text. Klíč idempotence nelze znovu použít s jinými proměnnými nebo jiným kontextem.

### CSV kampaně

Sloupce CSV jiné než telefonní číslo jsou již uloženy jako proměnné kontaktu. Každé volání je nyní používá automaticky. Použijte záhlaví jako `name`, `account_id` a `appointment_slot`, aby odpovídala vašim zástupným symbolům. Stávající mapování jména může zkombinovat sloupce se jménem a příjmením do proměnné `name`. Kontakty kampaně nemají kontext pro jednotlivé kontakty.

### Webhook dynamické konfigurace

Na blokující cestě webhooku konfigurace vraťte uloženého agenta ve své
organizaci spolu s hodnotami pro konkrétní hovor. Pro agenta Full duplex si hovor zachová
hlas agenta, i když začne v jiném podporovaném jazyce:
mapování hlasů pro jednotlivé jazyky ani nativní přepínání hlasu se pro tento
hovor nepoužijí.

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

Proměnné v odpovědi přepíšou proměnné na úrovni požadavku, zatímco ostatní klíče požadavku zůstanou zachovány. Hodnota `null` v odpovědi vybere výchozí hodnotu zástupného symbolu. Sloučený objekt se také musí vejít do 32 KB. Odpovědi uloženého agenta přijímají pouze `agent_id`, `variables`, `context`, `language` a pro jednotlivý hovor
[`timezone`](/cs/guides/dynamic-call-config); pokud potřebujete nahradit výzvu nebo jiná nastavení, vraťte vloženou konfiguraci. Odpovědi webhooku uloženého agenta používají nasazené A/B rozdělení agenta při telefonních hovorech i hovorech z widgetu; proměnné se vykreslí po výběru varianty. Když odpověď nastaví `language` pro agenta, který nepoužívá Full duplex, hovor použije také vlastní hlas daného jazyka, pokud ho má agent pro tento jazyk nastavený. Odpověď obsahující `prompt` vždy používá vloženou konfiguraci: jakékoli `agent_id` v této odpovědi se ignoruje, včetně hodnoty null nebo neceločíselných metadat. Vložená výzva stále musí projít běžnou validací. Vložené odpovědi webhooku mohou také obsahovat `variables` a `context`. Hodnota `context`, která není řetězcem nebo je příliš dlouhá, výměnu neprovede: telefonní hovor bude odmítnut a požadavek na relaci widgetu selže s `400`. Odpovědi webhooku uloženého agenta používají nasazené A/B rozdělení agenta při telefonních hovorech i hovorech z widgetu; proměnné se vykreslí po výběru varianty. Pro příchozí telefonní hovory použijte číslo bez přiřazeného příchozího agenta a nakonfigurujte jeho webhook telefonního čísla nebo organizace; klíče widgetu používají `mode="webhook"`. Příchozí oznámení systému endpointů neposkytují blokující konfigurační odpovědi.

### Webhook nastavení hovoru agenta

Chcete-li ponechat číslo přiřazené k jeho agentovi a vyplňovat pouze hodnoty hovoru, poskytněte agentovi [webhook pro nastavení hovoru](/cs/webhooks/call-incoming).
Před každým příchozím hovorem, který agent přijme na daném čísle, webhook obdrží hovor a ID, název a verzi agenta a odpoví stejnými hodnotami `variables`, `context`, `language` a `timezone` pro konkrétní hovor jako výše, aniž by vyžadoval `agent_id`. Agent,
jehož nastavení používá zástupný symbol bez výchozí hodnoty, potřebuje tento webhook, aby mohl přijmout hovor na telefonním čísle: při selhání webhooku se hovor nezahájí. Zástupné symboly s výchozí hodnotou, například `{{name|there}}`, umožňují agentovi přijmout hovor i bez něj.

### Hlavičky SIP

Hovory, které se k agentovi dostanou přes SIP (na [SIP adresu](/cs/guides/sip-addresses) nebo
na číslo s ručním připojením SIP), mohou přenášet kontext v hlavičkách `X-*` a
`User-to-User`. Každá z nich se stane proměnnou `sip_`, například
`{{sip_x_amzn_connectcontactid}}` nebo `{{sip_uui}}`, s nejnižší
prioritou: hodnota se stejným názvem z API nebo webhooku má přednost. Viz
[Předávání kontextu hovoru v hlavičkách SIP](/cs/guides/sip-addresses).
Hodnoty hlaviček nastavuje odesílatel, proto je považujte za nedůvěryhodné,
stejně jako jakoukoli hodnotu poskytnutou prohlížečem.

### API relace widgetu

`POST /v1/widget/session` přijímá `variables` a `language` na nejvyšší úrovni. Jeho klíč určený k publikování
vybírá uloženého agenta. Klíče v režimu webhooku předávají tyto hodnoty do
konfiguračního webhooku a slučují odpověď, jak je popsáno výše.
Hodnoty `variables` widgetu dodané prohlížečem jsou řízené klientem, po výše
popsaném ověření a vyčištění řetězců jsou doslovně předány v `web.incoming`
a zopakovány ve webhoocích po dokončení a historii hovorů. Nepovažujte je za
důvěryhodné údaje o identitě ani autorizaci.

Vlastní pole `context` widgetu v prohlížeči je jiné: přenáší text ze
stránky, na které se návštěvník nachází a který agent považuje za obsah webu (viz
[Vložení webového widgetu](/cs/guides/embed-web-widget)). Kontext konkrétního volání widgetu
pochází z konfiguračního webhooku klíče v režimu webhooku, jak je uvedeno výše. Pokud má
volání oba, nejprve se použije kontext konkrétního volání a poté obsah stránky.

### API relace v reálném čase

`POST /v1/realtime/sessions` přijímá `variables`, `context` a `language` na nejvyšší úrovni
spolu s `agent_id` nebo vloženým `config`:

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

`context` patří pouze na nejvyšší úroveň; vložený `config` jej odmítne jako
neznámé pole.

### Realtime WebSocket

U uloženého agenta zůstává nasazený prompt uloženého agenta jeho promptem.
`session.instructions` se stává kontextem hovoru, `session.prompt.variables`
(nebo `session.config.variables`) se stávají jeho proměnnými a `session.language`
se stává jeho jazykem pro daný hovor. Agenta vyberte pomocí
`session.prompt.id` v první zprávě `session.update`, která spustí relaci, jakmile
tato aktualizace dorazí:

```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 připojení spustí agenta hned po připojení socketu, ještě
před jakýmkoli `session.update`, takže neobsahuje žádný vstup pro konkrétní hovor. Přidejte
`&wait_for_session_update=1`, chcete-li počkat na první `session.update` a použít jeho
instrukce a proměnné.

V inline relaci (bez uloženého agenta) je `session.instructions` samotná výzva stejně jako dříve. Testovací hovory v prohlížeči a simulace doplní výchozí hodnoty a chybějící zástupné symboly. Chcete-li testovat s hodnotami, uložte u agenta
[ukázku nastavení hovoru](/cs/webhooks/call-incoming) a vyberte ji při spuštění testu; hovor proběhne, jako by na něj odpověděl váš webhook pro nastavení hovoru.

## Po hovoru

`GET /v1/calls`, `GET /v1/calls/{call_id}`, `telephony.complete` a `web.complete` obsahují
konečné sloučené `variables` a `unresolved_variables`. Starší datové obsahy dokončení,
které obsahují `data.history`, je obsahují také:

```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 vyplněnými proměnnými a přidaným blokem kontextu.

Uložte identifikátor CRM nebo úkolu do objektu proměnných, abyste dokončený
hovor propojili zpět s jeho zdrojovým záznamem. Proměnné a kontext se uchovávají
spolu se záznamem hovoru; odesílejte pouze informace, které je vhodné uchovávat
v historii hovorů a webhookech.

Přehrání hovoru v [ověřovacích sadách](/api-reference/validation-sets),
[spuštěních přehrávání](/api-reference/replay-runs) a
[šetřeních](/api-reference/investigations) používají proměnné a kontext daného
hovoru spolu s testovanou výzvou, takže přehrání testuje, co by bylo agentovi
při daném hovoru sděleno.

## Kompatibilita stávajících promptů

Vykreslování se vztahuje také na stávající prompty uložených agentů a variant A/B, vložené konfigurace odchozích a realtime hovorů a prompty vrácené webhooky konfigurace. Neznámé zástupné symboly `{{name}}` se změní na prázdný text, i když nejsou zadány žádné `variables`. Před nasazením zkontrolujte stávající prompty, včetně externě dodávaných vložených promptů a promptů webhooků, které ThunderPhone nemůže inventarizovat. Testovací hovory v prohlížeči a simulace používají stejné výchozí chování s prázdným textem, pokud nevyberete uložený vzorek nastavení hovoru.
