> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hubtalk.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Поля и переменные

> Схема полей строки запроса, формы полей V2, карта переменных агента, резервные значения, rl_today и сигнатурные переменные.

# Поля и переменные

Вкладка **«Поля и переменные»** в окне скрипта реестра. Справа — поля запроса V2, слева — переменные опубликованной версии агента и откуда каждая получит значение. Поле без записи уходит агенту как есть, под своим именем.

![Вкладка «Поля и переменные»](https://mintcdn.com/hubtalk/imXtUGq2OJsLMMCI/images/v4_adapter_registry_fields.png?fit=max\&auto=format\&n=imXtUGq2OJsLMMCI\&q=85\&s=b447cc33d2417572a02009efcea8db54)

1. Поиск переменных агента.
2. «Из полей запроса»: переменные, которые получат значение из полей; «как есть» — поле без записи.
3. «Подставит ядро адаптера»: `rl_today` — день кампании.
4. «Без значения»: действует умолчание агента; сигнатурная переменная здесь — красный блокер.
5. Строка поля: имя, форма (`str 0–150`), назначение «→ как есть».
6. Элементы строки: ручка ⋮⋮ слева — перетащить, ⚙ настройки, × убрать. Стрелки ↑↓ для порядка появляются при наведении на строку.
7. «Добавить поле» по одному или «Вставить список полей» — по имени на строку.

Порядок полей справа — это порядок, в котором V2 перечисляет ошибки строки.

## Как добавить поля

**1. Снимите схему строки с реального запроса клиента**

Все ключи строки `data[]`, кроме четырёх общих, должны быть полями схемы. Лишний ключ в запросе даёт отказ «#ключ#  does not exist in the format of the request», пропущенный — «The required field is missing #ключ#». Все поля схемы обязательны в каждой строке.

**2. Вставьте список полей**

Кнопка **«Вставить список полей»**, по одному имени на строку. Каждое имя становится полем `str 0–150` с любыми символами и уходит агенту как есть. Дубли пропускаются, итог — «Добавлено N, пропущено M».

**3. Выставьте порядок**

Перетаскиванием за ручку ⋮⋮ или стрелками ↑↓, которые появляются при наведении на строку. Порядок важен для текста ошибок V2 и ни для чего больше.

**4. Откройте ⚙ у поля и уточните форму**

См. [Формы полей](#формы-полей). Форма и пределы повторяют проверки V2: строка, которую отверг бы V2, отвергнет и адаптер.

**5. Назначьте переменную агента**

«Как есть», «В переменную» или «Не передавать». Проверьте левую панель: ни одна сигнатурная переменная агента не должна остаться «без значения».

![Настройки поля](https://mintcdn.com/hubtalk/imXtUGq2OJsLMMCI/images/v4_adapter_registry_field_settings.png?fit=max\&auto=format\&n=imXtUGq2OJsLMMCI\&q=85\&s=790c7fcacbebc8f51c06a7a851cd08da)

Настройки поля `agent_name`: форма `str 0–150`, уходит агенту как есть.

1. Имя поля — ключ в строке запроса.
2. Форма: `str`, `int`, `dte`, `dte_usa`, `arr`.
3. Длина для `str` (или «Значение» от/до для `int`).
4. Символы для `str`: `abc`, `123`, `alphabet`, `ru`, `arabic`.
5. Переменная агента: «Как есть», «В переменную», «Не передавать».
6. Резервное значение, если пришло пустым: запрос → резерв → умолчание агента → пусто.

## Формы полей

| Форма | Параметры | Что делает проверка |
| - | - | - |
| `str` · строка | Длина от/до (по умолчанию 0–150). Символы: `abc` — любые, `123` — только цифры, `alphabet` — без цифр, запятой, точки и скобок, `ru` — кириллица и пробел без «ё», `arabic` — арабское письмо. | Значение обрезается по краям, проверяются длина и набор символов. Не прошло — ошибка строки по этому полю. |
| `int` · целое число | Значение от/до (по умолчанию 0–2 000 000 000). | Запятая меняется на точку, число округляется вверх, проверяются пределы; агенту уходит строкой. |
| `dte` · дата | — | Принимается `д.м.гггг` или порядковый номер дня Excel; агенту уходит как `ДД.ММ.ГГГГ`. |
| `dte_usa` · дата в формате США | — | То же для `м/д/гггг`; агенту уходит как `ММ/ДД/ГГГГ`. |
| `arr` · значение из списка | Значения; «Неизвестное значение»: «Отказ всего запроса» или «Заменить на …». | Значение не из списка — отказ или замена. |

## Назначение переменной

| Режим | Что получает агент |
| - | - |
| **Как есть** | Переменную с именем поля. Работает, если у агента есть переменная с таким именем; регистр, подчёркивания, дефисы и пробелы при сравнении не различаются. |
| **В переменную** | Переменную агента с другим именем, выбранную из списка. Две записи не могут вести в одну переменную. |
| **Не передавать** | Ничего: поле проверяется и хранится, но агенту не уходит. |

* **Резервное значение** доступно только у `str` с минимальной длиной 0: пустое значение других форм V2 не пропускает. Порядок: значение из запроса → резервное значение → умолчание агента → пусто. Пустое значение без резерва агенту не передаётся вовсе, и тогда действует умолчание переменной в агенте. Резерв должен укладываться в форму поля и быть не длиннее 1000 символов.
* **`foreign_id`** — внешний идентификатор записи у клиента. По умолчанию агенту не передаётся; запись «В переменную» кладёт его копию в переменную агента. Резерва у него нет.
* **Зарезервированные имена**: `phone_number`, `type`, `gender_voice`, `language` и служебные колонки загрузки контактов (`phone`, `mobile`, `cell`, `msisdn`, `timezone`, заголовки группы договора и роли). Их нельзя сделать полем схемы или целью записи.
* **Переменные, которые ставит платформа** (`from_number`, `to_number`, `today`, `call_date` и подобные), целью записи быть не могут.

> [!NOTE]
>
> **`rl_today` и сигнатурные переменные.** Ядро адаптера подставляет ровно одну переменную — `rl_today`, день кампании в формате `ДД.ММ.ГГГГ`. Она перекрывает одноимённое поле запроса.
>
> Сигнатурные переменные агента (в левой панели помечены «подпись») обязаны получить значение — из поля, из записи карты или от ядра, иначе скрипт не сохранится: кампании без сигнатурных переменных не запускаются. Про переменные агента — [Переменные](https://docs.hubtalk.ai/ru/v4/tutorial/variables.md).

## Как поле попадает к агенту: итоговый порядок

Для каждой строки `data[]`:

1. Общие поля: `phone_number` и `type` переменными не становятся никогда; `gender_voice` и `language` уходят агенту переменными под своими именами.
2. Поле схемы без записи в карте уходит как есть, под именем поля.
3. Запись «В переменную» переименовывает поле в выбранную переменную агента; «Не передавать» — поле не уходит.
4. Пустое значение берёт резервное значение записи; без резерва ключ не передаётся, и действует умолчание переменной в агенте.
5. `foreign_id` уходит агенту только через запись «В переменную».
6. Последней ядро пишет `rl_today`.

В агенте переменные используются как `{{имя}}`. Где проверить, что дошло до агента, — в разделе [Передача переменных агенту](https://docs.hubtalk.ai/ru/v4/compat-adapter/faq-variables.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.