> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.ada.cx/docs/automation/variables/best-practices/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.ada.cx/_mcp/server.

# Best practices

## Overview

For Messaging integrations, use [`setMetaFields`](/messaging/web/sdk-api-reference#setmetafields) with flat values that meet the [SDK metadata limits](/messaging/introduction/reporting-differences-from-the-chat-sdk#meta-field-limits).

Variables are essential for creating dynamic, personalized, and context-aware experiences. They allow your AI Agent to collect information from end users, track conversation state, and pass data into elements like [Actions](/docs/automation/tools/api-tools) and [Playbooks](/docs/automation/playbooks). This topic outlines best practices for designing, storing, and reusing Variables effectively, along with common pitfalls and examples of good variable usage.

## Use clear and specific variable names

Choose names that describe what the variable stores, rather than generic labels. Clear naming helps both the AI Agent and future builders understand the variable's purpose.

**Good examples**

* `user_email`
* `shipping_address`
* `account_tier`

**Avoid**

* `value`
* `input1`
* `temp`

> **Tip**
>
> Descriptive variable names improve Autocapture accuracy and makes them easier to maintain.

## Use Autocapture variables for conversational data

[Autocapture Variables](/docs/automation/variables/using-variables#autocapture-variables) perform best when the information is something the end user will naturally state during the conversation (such as email, phone number, or order number).

**Use Autocapture when**:

* The target value will appear in the transcript
* The context is natural (e.g., the end user says "My order number is 12345")
* You want the AI Agent to prompt only when needed

**Avoid Autocapture when**:

* The end user might phrase the answer ambiguously
* The information needs precise formatting

> **Info**
>
> Autocapture works best in English and may not perform consistently in other languages.

## Use Global variables for values needed across multiple steps

[Global Variables](/docs/automation/variables/using-variables#global-variables) persist and can be reused across [Actions](/docs/automation/tools/api-tools), [Playbooks](/docs/automation/playbooks), [Processes](/docs/automation/processes), and other elements.

**They are ideal for**:

* Persistent end user details (e.g., order number)
* Context used across multiple steps

**Avoid storing**:

* Large API responses
* Data that changes frequently
* Sensitive details that do not need to persist

> **Tip**
>
> Variable reuse depends on identity continuity. To learn how the system determines whether an end user is returning, see [Conversation identifiers and persistence](/docs/optimization/conversations/conversation-identifiers-and-persistence).

## Use Sensitive variables for confidential information

[Sensitive variables](/docs/automation/variables/using-variables#sensitive) should be used for personally identifiable or sensitive data.

Sensitive variables:

* Are redacted in the dashboard
* Are deleted automatically after 24 hours
* Should be used for anything you do not want stored long-term

## Use metavariables for environment and channel context

[Metavariables](/docs/automation/variables/using-variables#metavariables) give your AI Agent information about the end user's device, browser, channel, and system state.

Common use cases:

* Personalizing content based on language or timezone
* Handling browser-specific behavior

Metavariables **cannot** be created manually. They are populated automatically or passed via [`setMetaFields()`](/chat/web/sdk-api-reference#setmetafields) in your embed script.

## Minimize the size of stored data

Variables can store up to 100,000 characters, but smaller values are better for performance and maintainability.

Best practices:

* Store only the specific fields you need
* Avoid storing large JSON responses
* Parse and extract needed values before saving

> **Info**
>
> Storing large payloads may cause the variable to exceed the size limit or impact the performance of your AI Agent.

## Avoid re-asking for information unnecessarily

Before using a **Capture** block, check whether the value already exists.

Use **Set Variable** or **Conditional** block to:

* Skip asking for information that has already been collected
* Reuse verified data
* Reduce friction and create smoother conversations

## Use metadata for logged-in end user information

Avoid asking end users to repeat information that your system already knows. Use `setMetaFields()` to pass things like:

* email address
* account tier
* subscription level

This ensures consistency and reduces effort for authenticated end users.

## Test variable behavior with different end user identities

Variable persistence depends on how Ada recognizes end users. Test with:

* Returning Web Chat end users
* New private-mode sessions
* Different devices and browsers
* Email threads inside and outside the continuation window
* Social channel interactions

> **Tip**
>
> Identity testing helps ensure variables behave correctly across channels and repeat visits. For more information, see [Conversation identifiers and persistence](/docs/optimization/conversations/conversation-identifiers-and-persistence).

## Keep your variable set organized

Variable sets can grow over time! Keep them clean by:

* Reviewing unused variables periodically
* Maintaining clear descriptions
* Grouping variables by use case
* Standardizing naming conventions

## Common mistakes

Here are some common errors that can impact performance or end user experience.

#### Storing too much data

Variables that store entire API responses or large JSON objects may exceed the character limit or become difficult to work with.

#### Relying too heavily on Autocapture

Autocapture may misinterpret ambiguous inputs or fail in non-English languages.

#### Using Global variables for sensitive data

Sensitive details should be stored only in Sensitive variables.

#### Assuming variables always persist

Variable reuse depends on identity, channel rules, and persistence settings. A new end user session may clear Global variable values.

## Examples

#### Store only the fields you need

**Correct**

```json
{ "order_status": "shipped" }
```

**Avoid**

```json
{
  "order_id": "12345",
  "items": [...],
  "shipping": {...},
  "customer": {...},
  "metadata": {...}
}
```

Store only the fields you actually intend to use.

#### Use setMetaFields for logged-in end users

**Correct**

```js
setMetaFields({ email: user.email, account_id: user.id });
```

**Avoid**
Asking the end user: *"What is your email address?"* for authenticated sessions.

#### Check before asking

**Correct**
If `user_email` exists, no need to capture it in a variable.

**Avoid**
Asking the end user for their email every time the process runs.

---

Have any questions? Contact your Ada team, or email us at [](mailto:help@ada.cx?subject=Help%20Docs%20inquiry).