---
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 КБ 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` (см. ниже).
- Начальные и конечные пробельные символы удаляются, также удаляются те же управляющие символы и символы форматирования, что и в значениях переменных.
- Контекст является частью промпта звонка, поэтому он учитывается в [размере промпта](/ru/guides/pricing) звонка.

В агенте с [этапами](/ru/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` — в том же поле, которое возвращает вебхук конфигурации; если передаёте оба варианта, текст должен совпадать. Ключ идемпотентности нельзя повторно использовать с другими переменными или другим контекстом.

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

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

### Вебхук динамической конфигурации

В блокирующем маршруте вебхука конфигурации верните сохранённого агента из вашей организации и любые значения для конкретного звонка. Для агента 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 КБ. Ответы сохранённого агента принимают только
`agent_id`, `variables`, `context`, `language` и часовой пояс для каждого звонка
[`timezone`](/ru/guides/dynamic-call-config); возвращайте встроенную конфигурацию, если нужно
заменить промпт или другие настройки. Ответы вебхука сохранённого агента
используют опубликованное A/B-распределение агента как для телефонных звонков, так и для вызовов через виджет;
переменные обрабатываются после выбора варианта. Если ответ задаёт `language` для
агента без полного дуплекса, для звонка также используется собственный голос этого языка, если
для него задан голос агента. Ответ, содержащий `prompt`, всегда использует встроенную
конфигурацию: любой `agent_id` в таком ответе игнорируется, включая метаданные со значением null или
нецелочисленные метаданные. Встроенный промпт всё равно должен пройти обычную проверку.
Встроенные ответы вебхука также могут содержать `variables` и `context`. `context`,
который не является строкой или слишком длинный, завершает обмен с ошибкой: телефонный звонок
отклоняется, а запрос сеанса виджета завершается с `400`. Ответы вебхука сохранённого агента
используют опубликованное A/B-распределение агента как для телефонных звонков, так и для вызовов через виджет;
переменные обрабатываются после выбора варианта. Для входящих телефонных звонков используйте номер, к которому не назначен агент для входящих
звонков, и настройте вебхук номера телефона или организации; ключи виджета используют
`mode="webhook"`. Входящие уведомления системы конечных точек не предоставляют блокирующие
ответы конфигурации.

### Вебхук настройки звонка агента

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

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

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

### API сеанса виджета

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

Собственное поле браузерного `context` виджета отличается: оно содержит текст со
страницы, открытой у посетителя, который агент воспринимает как содержимое веб-сайта (см.
[Встраивание веб-виджета](/ru/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`, как и прежде, является самим промптом. Тестовые звонки в браузере и симуляции подставляют значения по умолчанию и отсутствующие заполнители. Чтобы протестировать со значениями, сохраните на агенте [пример настройки звонка](/ru/webhooks/call-incoming) и выберите его при запуске теста; звонок выполняется так, как если бы ваш вебхук настройки звонка ответил этим примером.

## После звонка

`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, встроенным конфигурациям исходящих и realtime-звонков, а также к промптам, возвращаемым вебхуками конфигурации. Неизвестные заполнители `{{name}}` становятся пустым текстом, даже если `variables` не переданы. Перед запуском проверьте существующие промпты, включая встроенные промпты и промпты вебхуков, предоставленные внешними системами, которые ThunderPhone не может выявить.
Тестовые звонки в браузере и симуляции используют такое же поведение по умолчанию с пустыми значениями, если только вы не выберете сохранённый пример настройки звонка.
