# App data

## Variables

A variable is a named value the app remembers about a person: a name from an input field, a chosen product, an external service's response. Every app user has their own variables: what one person entered, another will not see.

You do not need to create variables in advance. It is enough to specify a name where the value is written — in the "Variable" field of an element or block. The builder remembers the names from the scheme and suggests them as you type.

![Variable name suggestions in the Variable field](https://support.watbot.org/_media/en/02-mini-apps/_images/variable-hint.webp?v=1791781230)

Where values come from:

| Source | What it writes |
|---|---|
| Input fields | What the person entered or chose — into the variable from the "Variable" field |
| "List records" and other elements where a row is chosen | The id of the chosen row — into the variable from the element's settings |
| "HTTP request" | The whole response, the status code and individual values from the response |
| "Find a record" | The columns of the found record |
| "Add a record", "Record form" | The id of the new record |
| "JavaScript", app code, "HTML code" | The variables the code is allowed to write — see [Code in the app](https://support.watbot.org/mini-apps/code) |

A few more variables are filled in by the app itself at launch. You cannot write anything of your own into them:

| Variable | What it holds |
|---|---|
| `launchSource` | Where the app was opened from: `telegram`, `max`, `webchat`, `pwa` or `browser` |
| `startParam` | The launch link parameter — what comes after `startapp`. How to pass it is on the [Versions and publishing](https://support.watbot.org/mini-apps/publish) page |
| `contactTags` | The bot contact's tags, comma-separated |
| `appTags` | The app user's tags, comma-separated |

A person's variables are visible in their card in the "Users" section, and you can edit them there. The "Debug" panel shows how variables change in the preview.

**Limits.** A variable name is up to 64 characters, a value up to 4096. One user can have up to 500 variables: new ones beyond that are not written.

## Templates

A variable's value is inserted into text with double curly braces: `{{ name }}`. Templates work in screen texts and headings, in captions, in default field values, in the URL and body of an HTTP request, in column values and record selection conditions, in bot messages.

Example: an input field writes the name into the `name` variable, and on the next screen the heading "Thank you, `{{ name }}`!" turns into "Thank you, Anna!".

If there is no such variable, its place stays empty. Only the variable's value is inserted: the expressions and functions that work in the chatbot's templates are not supported here.

> [!TIP]
> In the builder fields where a value is written, start typing the name — the suggestion inserts the whole template. In fields where a result is written, the suggestion inserts the bare variable name.

### Bot contact data

If the app is opened from a bot and the person has written to that bot, the fields of their contact are available:

| Template | What it holds |
|---|---|
| `{{ contact.id }}` | The contact's number |
| `{{ contact.name }}`, `{{ contact.first_name }}`, `{{ contact.last_name }}` | Full name, first name, last name |
| `{{ contact.username }}` | The username in the messenger |
| `{{ contact.phone }}`, `{{ contact.email }}`, `{{ contact.address }}` | Phone, email, address |
| `{{ contact.source }}` | The contact's channel |
| `{{ contact.created_at }}` | When the contact appeared in the bot |
| `{{ contact.start_message }}` | The first message to the bot |
| `{{ contact.telegram_id }}`, `{{ contact.max_id }}` | The id in Telegram and MAX |

The contact's own variables are read with the prefix too: `{{ contact.city }}` — the `city` variable from the contact card.

App variables and bot contact variables are different. A value from an app field does not get into the contact, and a contact variable is not visible in the app without the `contact.` prefix. Only the code of the "JavaScript" block can write a variable to the contact. A guest from a browser has no contact — the `contact.` fields are empty.

## Lists

The app stores data in the project's lists — the same ones the chatbots work with: [Lists](https://support.watbot.org/lists). A list filled in the app is visible in the "Lists" section of the project's menu, and vice versa. The app will not open someone else's list — one from another project.

The app can fill fields of the "Text", "Number", "Money", "Yes/No", "Date" and "Date and time" types. "File", "Image", "Contact ID" and "Bot ID" fields cannot be filled from the app.

| Task | What to use |
|---|---|
| Show a catalogue, a schedule, reviews | The "List records" element |
| Open one record on a separate screen | A tap on a record puts its id into a variable (`recordId` by default); the next screen shows it with the "Record card" element or puts it into variables with the "Find a record" block |
| Accept a request or a questionnaire | The "Record form" element, or input fields plus the "Add a record" block |
| Let a person correct their record | "Record form" in the "Changes a record" mode or the "Edit a record" block |
| Delete a record | The "Delete a record" block |

### Selection and sorting

"List records" and the record blocks have "Conditions": "Column", "Condition" and "Value". Conditions: "Equals", "Contains", "Starts with", "Ends with", "Greater than", "Less than", "Empty", "Filled". Up to 20 conditions.

You can insert a variable into the value — then the selection depends on what the person chose. For example, a search field writes to `query`, and the condition "Title" "Contains" `{{ query }}` shows the matching records.

"Sorting" — a column and the "Descending" or "Ascending" direction. Empty — newest records first.

"How many to show" — this many records are loaded at once; with "Load more while scrolling" ticked, the next ones load when the person scrolls to the end. The app returns no more than 50 records at a time.

![List records element: what to show, filtering and sorting](https://support.watbot.org/_media/en/02-mini-apps/_images/records-element.webp?v=1791781230)

### Own records

A record can be tied to the person who created it: "The record belongs to the user" in "Record form" or "Attach the record to the current user" in the "Add a record" block. This works for a guest from a browser too.

With "Only the current user’s records" ticked, an element or block sees only this person's records — this is how "my requests", "my orders" and favourites are made. In the "Edit a record" and "Delete a record" blocks this tick is on by default: without it, a person could substitute someone else's id and change someone else's record.

## Forms

The "Record form" element is a shortcut from a screen to a record: each form field is a list column, and submission immediately creates or changes a record. No separate block is needed; the form's exit fires after a successful submission.

1. Add a "Record form" to the screen and choose the "List".
2. In "What the form does", leave "Adds a record" or choose "Changes a record". For changing, specify "Which record to change" — usually the variable that a tap on a list record puts in. The "Show the record values in the fields" tick fills the fields with the current values.
3. Add "Form fields" — one by one or with the "Fields for every column" button. A field gets a label from the column name.
4. Set up validation: "Required field", length and "Pattern (regular expression)" for text, "Value bounds" for a number, "Date bounds" for a date. The "Error text" is shown instead of the standard one.
5. In "Submit button", set the button's label, colour and style. In "After submitting" — the variable for the id of the new record.
6. Draw a link from the form's exit to the "Thank you" screen.

![Record form element: list and form fields](https://support.watbot.org/_media/en/02-mini-apps/_images/record-form.webp?v=1791781230)

Values are checked once more on the server. While there are errors, the form stays on the screen and highlights the fields. The default error texts: "Please fill in this field", "Enter a number", "Enter a date", "The value must be at least …", "The value must be at most …", "At least … characters", "No more than … characters", "The value does not match the format".

**Form limits:**

- up to 50 fields;
- up to 5000 characters are saved from a field;
- one visitor creates up to 60 new records per hour through forms. Beyond that — the message "Too many form submissions in a row, please try again later."

## Tags

There are two kinds of tags in the app.

| | User tags | Contact tags |
|---|---|---|
| Whose | The app's own — everyone who opened it has them, even without a bot | The chatbot contact's — the same as in the contact card |
| How they change | The "User tags" block, manually in the user card | The "Contact tags" block. A bot contact is needed |
| Where they are visible | The user card in the "Users" section | The bot's contact card |
| Variable | `appTags` | `contactTags` |

![User tags block](https://support.watbot.org/_media/en/02-mini-apps/_images/tags-block.webp?v=1791781230)

Conditions work with tags: "User tag" and "Contact tag" with the "has tags" and "has no tags" comparisons. You can list several tags — one of them is enough. Tags are compared case-insensitively.

One person can have up to 500 tags: new ones beyond that are not added.

## Conditions

Conditions are set the same way in the "Condition" block and in the "Display condition" of an element, area or header button.

- "How to combine": "All conditions" or "Any condition".
- Each comparison has "What to check", "Comparison" and "Value". Up to 20 comparisons.

![Condition block settings: a variable and a user tag](https://support.watbot.org/_media/en/02-mini-apps/_images/condition.webp?v=1791781230)

| "What to check" | What it looks at |
|---|---|
| "A variable" | Any variable — its name is specified in the "Variable" field |
| "Launch source" | Where the app was opened from: "Browser", "Home screen (PWA)", "Telegram", "MAX", "Web chat". Comparisons — `=` and `!=` |
| "Link parameter" | What came after `startapp` in the link: it tells traffic sources and campaigns apart |
| "Contact tag" | The contact's tags in the chatbot |
| "User tag" | The app's tags |

Comparisons: `=`, `!=`, `>`, `<`, `>=`, `<=`, "contains", "does not contain", "is empty", "is not empty", "has tags", "has no tags". "Greater" and "less" compare numbers, "contains" compares text case-insensitively. You can insert a variable into the "Value": `{{ name }}`.

A display condition on a field of the same screen fires right away while the person fills in the field: for example, the "Comment" field appears only when the "Delivery needed" switch is on.