> ## 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.

# Fields and variables

> The request row field schema, V2 field forms, the agent variable map, fallback values, rl_today and signature variables.

# Fields and variables

The **Fields and variables** tab in the registry script window. On the right are the V2 request fields; on the left are the variables of the agent's published version and where each gets its value. A field without an entry goes to the agent as is, under its own name.

![The Fields and variables tab](https://mintcdn.com/hubtalk/imXtUGq2OJsLMMCI/images/v4_adapter_registry_fields_en.png?fit=max\&auto=format\&n=imXtUGq2OJsLMMCI\&q=85\&s=bb267f0dbf1468fed3d760bcf31c0580)

1. Agent variable search.
2. **From the request fields**: variables that get a value from fields; "as is" — a field without an entry.
3. **Filled by the adapter core**: `rl_today` — the campaign day.
4. **Without a value**: the agent default applies; a signature variable here is a red blocker.
5. Field row: name, form (`str 0–150`), target "→ as is".
6. Row controls: the ⋮⋮ handle on the left — drag, ⚙ settings, × remove. The ↑↓ order arrows appear when you hover over the row.
7. **Add a field** one at a time or **Paste a list of fields** — one name per line.

The order of the fields on the right is the order in which V2 lists the errors of a row.

## How to add fields

**1. Take the row schema from a real client request**

All keys of a `data[]` row except the four common ones must be schema fields. An extra key in the request gives the refusal "#key#  does not exist in the format of the request", a missing one — "The required field is missing #key#". All schema fields are required in every row.

**2. Paste the list of fields**

The **Paste a list of fields** button, one name per line. Each name becomes a `str 0–150` field with any characters and goes to the agent as is. Duplicates are skipped; the result is "Added N, skipped M".

**3. Set the order**

Drag by the ⋮⋮ handle, or use the ↑↓ arrows that appear when you hover over the row. The order matters for the text of V2 errors and nothing else.

**4. Open ⚙ on the field and refine the form**

See [Field forms](#field-forms). The form and limits repeat the V2 checks: a row V2 would reject is rejected by the adapter too.

**5. Assign the agent variable**

**As is**, **Into a variable** or **Do not pass**. Check the left panel: no signature variable of the agent may remain "without a value".

![Field settings](https://mintcdn.com/hubtalk/imXtUGq2OJsLMMCI/images/v4_adapter_registry_field_settings_en.png?fit=max\&auto=format\&n=imXtUGq2OJsLMMCI\&q=85\&s=6233c81147e509f22dc4f15c817edfbb)

Settings of the `agent_name` field: form `str 0–150`, goes to the agent as is.

1. Field name — the key in the request row.
2. Form: `str`, `int`, `dte`, `dte_usa`, `arr`.
3. Length for `str` (or **Value** from/to for `int`).
4. Characters for `str`: `abc`, `123`, `alphabet`, `ru`, `arabic`.
5. Agent variable: **As is**, **Into a variable**, **Do not pass**.
6. Fallback value if the value arrived empty: request → fallback → agent default → empty.

## Field forms

| Form | Parameters | What the check does |
| - | - | - |
| `str` · string | Length from/to (0–150 by default). Characters: `abc` — any, `123` — digits only, `alphabet` — no digits, commas, dots or brackets, `ru` — Cyrillic and space, no letter yo, `arabic` — Arabic script. | The value is trimmed at the edges; length and character set are checked. If it fails — a row error on this field. |
| `int` · whole number | Value from/to (0–2,000,000,000 by default). | A comma is replaced with a dot, the number is rounded up, limits are checked; it goes to the agent as a string. |
| `dte` · date | — | Accepts `d.m.yyyy` or an Excel day serial number; goes to the agent as `DD.MM.YYYY`. |
| `dte_usa` · US date | — | The same for `m/d/yyyy`; goes to the agent as `MM/DD/YYYY`. |
| `arr` · a value of a list | Values; **Unknown value**: **Refuse the whole request** or **Replace with …**. | A value not on the list — refusal or replacement. |

## Variable assignment

| Mode | What the agent gets |
| - | - |
| **As is** | A variable with the field's name. Works if the agent has a variable with that name; case, underscores, hyphens and spaces are ignored in the comparison. |
| **Into a variable** | An agent variable with a different name, selected from the list. Two entries cannot go to the same variable. |
| **Do not pass** | Nothing: the field is checked and stored but not passed to the agent. |

* A **fallback value** is available only for `str` with a minimum length of 0: V2 does not let an empty value of other forms through. Order: value from the request → fallback value → agent default → empty. An empty value without a fallback is not passed to the agent at all, and the variable's default in the agent applies. The fallback must fit the field form and be no longer than 1000 characters.
* **`foreign_id`** — the external record ID on the client side. By default it is not passed to the agent; an **Into a variable** entry puts a copy of it into an agent variable. It has no fallback.
* **Reserved names**: `phone_number`, `type`, `gender_voice`, `language` and the service columns of contact upload (`phone`, `mobile`, `cell`, `msisdn`, `timezone`, contract group and role headers). They cannot be made a schema field or an entry target.
* **Variables set by the platform** (`from_number`, `to_number`, `today`, `call_date` and the like) cannot be an entry target.

> [!NOTE]
>
> **`rl_today` and signature variables.** The adapter core fills exactly one variable — `rl_today`, the campaign day in `DD.MM.YYYY` format. It overrides a request field of the same name.
>
> The agent's signature variables (marked **signature** in the left panel) must get a value — from a field, a map entry or the core — otherwise the script is not saved: campaigns without signature variables do not launch. For agent variables, see [Variables](https://docs.hubtalk.ai/v4/tutorial/variables.md).

## How a field reaches the agent: the final order

For each `data[]` row:

1. Common fields: `phone_number` and `type` never become variables; `gender_voice` and `language` go to the agent as variables under their own names.
2. A schema field without a map entry goes as is, under the field name.
3. An **Into a variable** entry renames the field to the selected agent variable; **Do not pass** — the field is not passed.
4. An empty value takes the entry's fallback value; without a fallback the key is not passed, and the variable's default in the agent applies.
5. `foreign_id` goes to the agent only through an **Into a variable** entry.
6. The core writes `rl_today` last.

In the agent, variables are used as `{{name}}`. Where to check what reached the agent — see [Passing variables to the agent](https://docs.hubtalk.ai/v4/compat-adapter/faq-variables.md).


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