Overview
Variable Inputs are pre-chat forms that collect specific information from users before they start conversations with AI agents. This feature ensures your agents have all the necessary context from the beginning, creating more personalized and effective interactions.
Learning Objectives:
Understand the purpose and benefits of Variable Inputs
Configure variables in agent system prompts
Set up different types of input fields
Test and implement pre-chat forms for your agents
Prerequisites
You'll Need:
Access to a workspace
Agent creation or editing permissions
Clear understanding of what information you need to collect
API endpoint details (for dynamic dropdown options, optional)
Understanding Variable Inputs
Benefits and Use Cases
Navigate to the Agents section
Click the "Agents" icon located in the left sidebar
Review your existing agents or prepare to create a new one
Understand key benefits of Variable Inputs
Personalized conversations: Collect specific information like client IDs or project names
Context-aware responses: Agents begin with complete scenario understanding
Streamlined workflows: Eliminate repetitive questions at conversation start
Consistent data collection: Gather required information in structured format
Tip: Consider what information your agent regularly asks for in the first few interactions - these are prime candidates for Variable Inputs.
Setting Up Variable Inputs
Define Variables in Your Agent's System Prompt
Access agent editing interface
Click the "Agents" icon in the left sidebar
Locate your agent in the list
Click the three-dot menu (⋯) next to the agent name
Select "Edit" from the dropdown menu
Insert variables in the Instructions field
Navigate to the "variables" section
Add variables clicking on the "+ Add" button
Result: The system will detect these variables and create input fields for them in the pre-chat form.
Note: Place variables naturally within context where they make grammatical sense in your instructions.
Configure Variable Input Settings
Navigate to the Variable Inputs configuration
In the agent edit interface, locate the tabs across the top
Click the "Variable Inputs" tab
Configure each variable field
Click on a variable name in the list to access its settings
Set the following properties:
Display Name: How the field appears to users
Input Type: Choose from text, dropdown, number, or date
Required: Toggle whether the field is mandatory
Default Value: Pre-populated information (optional)
Description: Help text for users (optional)
Validation: Rules to ensure valid input (optional)
Result: Each variable will be transformed into an appropriate input field in the pre-chat form.
Important: Give careful thought to which fields should be required versus optional. Required fields that are too specific might create barriers for users.
Configuring Input Field Types
Text Input Configuration
Set up text input fields
Select "Text" from the Input Type dropdown
Configure optional pattern validation if needed (for emails, phone numbers, etc.)
Set character limits if appropriate
Create dropdown selection fields
Select "Dropdown" from the Input Type dropdown
Choose between two option sources:
Static Options: Add each choice manually with display label and value
API Source: Connect to an external data source
Configure numeric inputs
Select "Number" from the Input Type dropdown
Set minimum and maximum values if needed
Specify step increments (e.g., allow only whole numbers)
Set up date selection fields
Select "Date" from the Input Type dropdown
Configure optional date range restrictions
Result: Each field will be presented with appropriate controls in the pre-chat form.
Setting Up Dynamic Dropdown Options
Configure API source for dropdown options
Select "Dropdown" as the Input Type
Choose "API Source" for the options source
Enter the API endpoint URL in the designated field
Configure authentication if required:
Header-based auth (e.g., API keys)
Basic auth (username/password)
Ensure proper API response format
Your API must return data in this format:
{
"options": [
{ "label": "Display Name 1", "value": "value1" },
{ "label": "Display Name 2", "value": "value2" }
]
}
Result: The dropdown will dynamically load options from your external system.
Testing and Implementation
Save and Test Your Configuration
Save your agent settings
Click the "Save" button at the bottom of the page
Wait for confirmation that changes have been applied
Test the user experience
Navigate to your agent's chat interface
Verify that the pre-chat form appears with all configured fields
Fill in the fields to test validation and user experience
Start the chat to confirm variables are correctly inserted into the conversation
Tip: Test with both valid and invalid inputs to ensure proper validation behavior.
Using System Variables
Access predefined system variables
Return to the agent editing interface
Navigate to the Instructions or System Prompt section
Add system variables using double curly braces:
{{DATE}}: Inserts the current date{{user.id}}: Inserts the ID of the current user{{user.name}}: Inserts the name of the current user{{user.email}}: Inserts the email of the current user
Result: These variables will be automatically populated with system values without requiring user input.
Best Practices
Keep forms concise: Only collect information that's truly necessary to avoid user friction
Use clear labels: Ensure users understand exactly what information is being requested
Provide helpful descriptions: Add context explaining why the information is needed
Set appropriate defaults: Pre-fill common values when possible to save user time
Add validation: Ensure data quality with appropriate input validation
Test thoroughly: Verify the user experience from different perspectives
Consider privacy: Only collect personal information when necessary and justified
Common Questions
Q: Can I make some fields optional and others required? A: Yes, each variable can be independently configured as required or optional using the toggle in the variable settings.
Q: How many variables can I add to a single agent? A: While there's no strict limit, it's best practice to keep the number of fields to 5-7 maximum to avoid overwhelming users.
Q: Can I pre-fill variables with user data? A: Yes, you can use system variables like {{user.name}} or set default values for any field.
Q: How do I update the options in a dropdown after initial setup? A: Return to the Variable Inputs tab in the agent edit interface and update the options for the specific dropdown field.
Q: Can users skip the form in urgent situations? A: If fields are marked as required, users must complete them. Consider which fields are truly necessary versus which could be optional.