Field keys and validation rules

Overview

Workflow steps that collect an answer can carry two optional settings:

A stable key: a fixed name for the collected value. Renaming the node, rewording a form label or translating the chat doesn't change it, so AI agents, integrations and other fields keep finding the value under the same name.
A validation rule: a small JSON rule that checks the answer. For example, it can check that mileage is between 0 and 2,000,000 km, that a model year is realistic, or that a US VIN has a correct check digit. A rule can also ask the visitor to confirm an unusually high value before the workflow moves on.

Rules apply in every workflow: ordinary chat workflows and workflows an AI agent offers (see Let an AI agent offer a workflow). Steps without a rule work exactly as before.

Steps

Set a stable key and rule on a single question

Open Chat → Workflows, open the workflow and click the node. Keys and rules are available on Question, Text Input, Name Input, Email Input, Phone Input, Date Input, Number Input, Currency Input and MultiSelect nodes.
In Stable output key, enter a key such as vehicle_make. Use lowercase letters, digits and _, starting with a letter (up to 100 characters). If you leave it empty, the key is made from the Node Name, for example "Vehicle make" becomes vehicle_make.
Optionally, enter a rule in Validation rule (JSON, optional), for example {"validator":"model_year"}.
Click Save. If the key or rule isn't valid, the panel tells you why, for example "Use a stable output key starting with a letter." or "Invalid validation rule: …", and nothing is saved.

Set stable keys and rules on a form

Click a Form Group node. Under Form Fields, each field has a label, a Stable key (e.g. vehicle_make) box, a type (Text, Email, Phone, Number or Date) and an optional rule box (Optional rule, e.g. {"unit":"km","minimum":0}).
Enter a unique stable key for each field. Keep it when you rename or translate the label.
Add a rule only to the fields that need one, then click Save.

Form fields are required unless their rule contains requiredWhen. Email and phone fields are checked automatically.

Rule reference

A rule is a JSON object with these keywords. Anything else is rejected when you save.

Keyword	Value	What it does
`minimum`	number	The answer must be a number at least this large.
`maximum`	number	The answer must be a number no larger than this.
`confirmationAbove`	number	A number above this is accepted only after the visitor confirms it. It must be above `minimum` and below `maximum`.
`unit`	`km`, `mi`, `year`, `usd` or `eur`	Records the unit the number is in. Values aren't converted.
`validator`	`vin_us` or `model_year`	`vin_us` accepts a 17-character US VIN (no I, O or Q) with a correct check digit. `model_year` accepts a year from 1886 to two years after the current year.
`requiredWhen`	`{"field": "<stable key>", "equals": "<value>"}`	Form fields only: the field is required only when another field (by its stable key) has this value, ignoring case. Otherwise it may be left empty.

Numbers may contain thousands separators, such as 425,000. A vin_us rule can't also contain numeric limits or a unit, and a model_year rule can only use the year unit.

Examples

Mileage in kilometres, confirming anything over 300,000 km:

{"unit":"km","minimum":0,"maximum":2000000,"confirmationAbove":300000}

Model year:

{"validator":"model_year","unit":"year"}

A VIN that's required only for US vehicles, on a form with a field whose stable key is market:

{"validator":"vin_us","requiredWhen":{"field":"market","equals":"US"}}

What visitors experience

An answer breaks the rule: the chat replies "Please enter a valid value." and asks the same step again.
An answer is above confirmationAbove: the chat replies "This value is unusually high. Please confirm that it is correct." In the website chat, the visitor clicks Confirm value. On text channels such as SMS or WhatsApp, the visitor replies confirm or sends the same value again. Any other answer is checked again from the start.
Both messages are shown in the visitor's chat language, such as Bulgarian.

Tips

Pick the key once and keep it. Integrations and AI agents that use the old key stop seeing the value if you change it.
In a workflow an AI agent offers, Fields returned to the agent lists the stable keys, so the agent receives mileage_km even if the label reads "Пробег".
Two steps in one workflow can't share the same explicit key; the attachment can't be saved until you change one.
Test a rule in Chat test with a valid value, an invalid one and one that needs confirmation.