Best practices

Overview

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 and 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

Use Autocapture variables for conversational data

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

Use Global variables for values needed across multiple steps

Global Variables persist and can be reused across Actions, Playbooks, 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

Use Sensitive variables for confidential information

Sensitive variables 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 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() 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

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

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.

Examples

1
{ "order_status": "shipped" }

1
{
2
  "order_id": "12345",
3
  "items": [...],
4
  "shipping": {...},
5
  "customer": {...},
6
  "metadata": {...}
7
}

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