---
title: "Променливи и контекст за всяко обаждане"
description: "Предоставете на всяко обаждане собствени подробности като именувани променливи за подканата или като свободно формулирана информация, без да променяте агента."
---

Всяко обаждане може да съдържа два вида входни данни за конкретното обаждане. Използвайте единия от тях или и двата заедно:

- **`variables`**: именувани стойности, които попълват `{{placeholders}}` в подканата. Използвайте ги за полета, към които подканата се отнася по име, например името на обаждащия се, номер на акаунт или час за среща.
- **`context`**: текст в свободна форма, добавен след подканата. Използвайте го за кратко описание, което не се вписва в шаблон, например описание на задачата за това обаждане или бележки, събрани по-рано.

И двете работят със запазен агент и с вградена конфигурация при всеки от описаните по-долу начини за започване на обаждане. Нито едно от тях не променя запазения агент, неговата история на версиите или другите му настройки.

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

## Променливи

Поставете заместители в подканата на вашия запазен агент, след което подайте обект `variables`
при започване на обаждане. ThunderPhone визуализира текста, преди да изпрати
конфигурацията на обаждането към гласовата среда за изпълнение.

Когато не са нужни стойности, пропуснете `variables`; не изпращайте `null` (отхвърля се с `400`).

### Заместители и стойности по подразбиране

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

Имената различават малки и главни букви и следват `[A-Za-z_][A-Za-z0-9_]*`. Интервалите около
името са разрешени; интервалите след `|` са част от стойността по подразбиране и се
запазват. `{{name|Friend}}` използва `Friend`, когато `name` липсва или е
`null`; празният низ е изрично подадена стойност. Липсващите стойности без
стойност по подразбиране стават празни низове и имената им се показват в `unresolved_variables`.
Текстът между двойни фигурни скоби, който не е валиден заместител, се премахва. Текстът в двойни
фигурни скоби във всяка подадена стойност се премахва независимо; дадена стойност не може да премахне
заобикалящ текст от подканата или друга стойност. Несъответстващите разделители с двойни фигурни скоби също се
премахват. JSON примерите в подканите не трябва да използват `{{`.
Стойностите са обикновен текст и никога не се оценяват
като код или не се разширяват рекурсивно като шаблони.

Променливите могат да се използват и в подканите за потвърждение, изходящите съобщения в гласова поща
и текста на съобщението за съгласие, когато това поле се изпраща за
телефонно обаждане. Агентът няма отделно поле `first_message`: поставете началните му
инструкции в подканата. Съществуващите заместители за гласова поща `{agent_name}` и `{org_name}`
продължават да работят.

### Стойности и ограничения

Стойностите може да са низове, числа, булеви стойности или `null`; булевите стойности се изобразяват като `true`
и `false`. Контролни Unicode (`Cc`) знаци с изключение на нов ред (`\n`), табулация (`\t`)
и връщане на каретката (`\r`), форматиращи (`Cf`) знаци с изключение на съединителя и несъединителя с нулева ширина (U+200C, U+200D, които изписват думи на езици с индийски и
арабски писмености), както и сурогатни (`Cs`) кодови точки се премахват; `\r\n`
се нормализира до `\n`. Всяка стойност
е ограничена до 2 000 знака при изобразяване. Подадените низове също се почистват и
съкращават преди съхранение. Оригиналният обект трябва да се побира в **32 KB UTF-8 JSON**; по-големите обекти получават `400` при заявки за обаждане/сесия, а
импортите на кампании отчитат невалидните редове поотделно. Масиви и вложени обекти не се
приемат като стойности. Несъответстващите ключове за метаданни (например CSV заглавка с
интервал) се запазват и връщат, но не може да бъдат използвани чрез контейнер.

## Контекст

`context` е низ с до **20 000 знака**. ThunderPhone го добавя след
подканата, след като променливите в подканата бъдат попълнени, като разграничен блок:

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

Агентът го прочита заедно със своите инструкции, затова го напишете така, както
бихте инструктирали колега преди обаждането. Контекстът не е шаблон:
`{{name}}` в него остава изписано както е. Ако текстът се нуждае от стойност, добавете стойността
сами преди изпращане.

- `null`, празен низ или низ само с интервали означава липса на контекст.
- Стойност, която не е низ или е по-дълга от 20 000 знака, се отхвърля с `400` при заявки за обаждания и сесии; от конфигурационен webhook тя прекратява обмена, както при невалидни `variables` (вижте по-долу).
- Началните и крайните интервали се премахват, както и същите контролни и форматиращи знаци като при стойностите на променливите.
- Контекстът е част от подканата за обаждането, така че се включва в [размера на подканата](/bg/guides/pricing) за обаждането.

При агент с [стъпки](/bg/guides/agent-steps) контекстът следва подканата на
всеки агент в обаждането, а не инструкциите на всяка стъпка.

## Откъде идват стойностите

### Изходящ API

Изпращайте `variables` и `context` чрез `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."
}
```

И двете работят и с изходящия агент по подразбиране на телефонния номер, или с вграден `config.prompt`. При вградена конфигурация `context` може да бъде и в `config` — същото поле, което връща webhook за конфигурация; ако изпратите и двете, те трябва да съдържат един и същ текст. Ключът за идемпотентност не може да се използва повторно с различни променливи или различен контекст.

### CSV за кампания

Колоните в CSV файла, различни от телефонния номер, вече се съхраняват като променливи за контакт. Всяко набиране вече ги използва автоматично. Използвайте заглавки като `name`, `account_id` и `appointment_slot`, за да съвпадат с вашите заместители. Съществуващото съпоставяне на име може да комбинира колоните за собствено и фамилно име в променливата `name`. Контактите от кампании нямат контекст за отделен контакт.

### Webhook за динамична конфигурация

В пътя на webhook за блокираща конфигурация върнете запазен агент от вашата организация, както и всички стойности за конкретното обаждане. При агент с Full duplex обаждането запазва гласа на агента дори когато започва на друг поддържан език: съпоставянията на гласове по езици и собственото превключване на гласове не се прилагат за това обаждане.

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

Променливите в отговора презаписват променливите на ниво заявка, а останалите
ключове на заявката се запазват. Стойност `null` в отговора избира стойността по подразбиране на заместителя.
Обединеният обект също трябва да се побира в 32 KB. Отговорите за запазен агент приемат само
`agent_id`, `variables`, `context`, `language` и
[`timezone`](/bg/guides/dynamic-call-config) за всяко обаждане; върнете вградена конфигурация, когато трябва да
замените подканата или други настройки. Отговорите от уебкука за запазен агент
използват внедреното A/B разпределение на агента както за телефонни обаждания, така и за обаждания чрез уиджет;
променливите се визуализират след избора на вариант. Когато отговорът задава `language` за
агент без Full duplex, обаждането използва и гласа за съответния език, ако
за агента е зададен такъв. Отговор, съдържащ `prompt`, винаги използва вградена
конфигурация: всеки `agent_id` в този отговор се игнорира, включително null или
метаданни, които не са цели числа. Вградената подкана все пак трябва да премине стандартната проверка.
Вградените отговори от уебкука могат също да включват `variables` и `context`. `context`,
който не е низ или е твърде дълъг, прави обмена неуспешен: телефонно обаждане
се отхвърля, а заявка за сесия чрез уиджет завършва с `400`. Отговорите от уебкука за запазен агент
използват внедреното A/B разпределение на агента както за телефонни обаждания, така и за обаждания чрез уиджет;
променливите се визуализират след избора на вариант. За входящи телефонни обаждания използвайте номер без зададен входящ
агент и конфигурирайте уебкуката за телефонния номер или организацията; ключовете за уиджет използват
`mode="webhook"`. Входящите известия от системата на крайната точка не предоставят блокиращи
отговори за конфигурация.

### Уебхук за настройка на обаждане на агент

За да запазите номер, присвоен на неговия агент, и да попълвате само стойностите за обаждането, задайте на агента [уебкука за настройка на обаждане](/bg/webhooks/call-incoming).
Преди всяко входящо обаждане, на което агентът отговаря чрез номер, уебкукът получава обаждането и идентификатора, името и версията на агента и отговаря със същите `variables`, `context`, `language` и `timezone` за конкретното обаждане, както по-горе, без да е необходим `agent_id`. Агент,
чиито настройки използват контейнер без стойност по подразбиране, се нуждае от този уебкук, за да отговори на телефонен номер: обаждането не започва, ако уебкукът е неуспешен. Контейнери със стойност по подразбиране, като `{{name|there}}`, позволяват на агента да отговори без него.

### SIP заглавки

Обажданията, които достигат до агент чрез SIP (чрез [SIP адрес](/bg/guides/sip-addresses) или
номер при ръчна SIP връзка), могат да носят контекст в заглавките `X-*` и
`User-to-User`. Всяка от тях става променлива `sip_`, например
`{{sip_x_amzn_connectcontactid}}` или `{{sip_uui}}`, с най-нисък
приоритет: стойност със същото име от API или webhook има предимство. Вижте
[Предаване на контекста на обаждане в SIP заглавки](/bg/guides/sip-addresses).
Стойностите на заглавките се задават от изпращача, затова ги третирайте като ненадеждни, както всяка
стойност, предоставена от браузър.

### API за сесия на уиджета

`POST /v1/widget/session` приема `variables` и `language` на най-горно ниво. Неговият публикуем
ключ избира запазения агент. Ключовете в режим на уебкука препращат тези стойности към
уебкуката за конфигурация и обединяват отговора, както е описано по-горе.
Предоставените от браузъра `variables` на уиджета се контролират от клиента, препращат се
дословно в `web.incoming` след описаните по-горе валидиране и почистване на низове
и се отразяват в уебкуките за завършване и хронологията на обажданията. Не ги третирайте
като надеждни данни за идентичност или оторизация.

Собственото браузърно поле `context` на уиджета е различно: то пренася текст от
страницата, на която се намира посетителят, който агентът третира като съдържание на уебсайта (вижте
[Вграждане на уеб уиджета](/bg/guides/embed-web-widget)). Контекстът за конкретно обаждане на уиджет идва
от уебкука за конфигурация на ключ в режим на уебкук, както е описано по-горе. Когато едно
обаждане има и двата, контекстът за конкретното обаждане е първи, следван от съдържанието на страницата.

### API за сесия в реално време

`POST /v1/realtime/sessions` приема `variables`, `context` и `language` на най-горно ниво
заедно с `agent_id` или вграден `config`:

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

`context` се поставя само на най-горно ниво; вграден `config` го отхвърля като
непознато поле.

### Realtime WebSocket

При запазен агент публикуваната подкана на запазения агент остава неговата подкана.
`session.instructions` става контекстът на обаждането, `session.prompt.variables`
(или `session.config.variables`) стават неговите променливи, а `session.language`
става езикът му за конкретното обаждане. Изберете агента чрез
`session.prompt.id` в първия `session.update`, който стартира сесията, щом
тази актуализация пристигне:

```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` в URL адреса на връзката стартира агента веднага щом сокетът
се свърже, преди какъвто и да е `session.update`, така че не включва входни данни за конкретния разговор. Добавете
`&wait_for_session_update=1`, за да изчакате първия `session.update` и да използвате неговите
инструкции и променливи.

Във вградена сесия (без запазен агент) `session.instructions` е самият
подканващ текст, както преди. Тестовите разговори с микрофона в Builder и симулираните разговори разрешават стойностите по подразбиране и липсващите заместители, но нямат променливи или вход за контекст за конкретен разговор.

## След обаждането

`GET /v1/calls`, `GET /v1/calls/{call_id}`, `telephony.complete` и `web.complete` включват
окончателните обединени `variables` и `unresolved_variables`. Наследените полезни товари за завършване,
които включват `data.history`, също ги включват:

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

`prompt_snapshot` на обаждането (`GET /v1/calls/{call_id}`) показва подканата на
агента с попълнени променливи и добавен блок с контекст.

Съхранявайте идентификатора на CRM или задачата си в обекта с променливи, за да свържете завършеното
обаждане с неговия изходен запис. Променливите и контекстът се запазват със записа на обаждането;
изпращайте само информация, която е подходяща за съхранение в историята на обажданията и
уебхуковете.

Повторните изпълнения на обаждане във [валидиращи набори](/api-reference/validation-sets),
[изпълнения за повторение](/api-reference/replay-runs) и
[разследвания](/api-reference/investigations) използват променливите и контекста на това обаждане
с подканата, която се тества, така че повторното изпълнение тества какво би било казано на агента
при това обаждане.

## Съвместимост със съществуващи подкани

Рендирането се прилага и към съществуващи подкани за запазени агенти и A/B варианти, вградени изходящи конфигурации и конфигурации в реално време, както и към подкани, върнати от уебхукове за конфигурация. Непознатите заместители `{{name}}` стават празен текст, дори когато не са предоставени `variables`. Проверете съществуващите подкани преди внедряване, включително външно предоставени вградени подкани и подкани от уебхукове, които ThunderPhone не може да инвентаризира. Обажданията с микрофон в Builder и симулационните обаждания прилагат същото поведение по подразбиране/празно.
