Variables are reusable placeholders that store values provided by users during a conversation.
They help you capture, store, and reuse information dynamically throughout your bot flows. By using variables, you can create more personalized interactions. For example, instead of sending a generic message like "Hey there! How can I assist you today?", you can greet the user by name with "Hey Mayur! How can I assist you today?".
Types of Variables ReplyCX supports three types of variables:
1. Conversation Variable
Conversation Variables are used to store temporary information that is only needed during the current conversation session.
Key Characteristics
• Session-specific and available only during the active conversation.
• Values do not persist once the conversation ends.
• Automatically reset when a new conversation starts.
• Ideal for storing temporary selections, responses, or flow-related information.
• Helps maintain context within a single interaction without affecting future conversations.
Example: Imagine a pizza-ordering bot asking "Which size would you like?" The customer's answer ("Large") only matters for that order — once the conversation ends, there's no reason to remember it. A conversation variable handles this perfectly.
2. Contact Variables
Contact Variables are designed to store user-specific information that remains available across multiple conversations. They are ideal for personalization and maintaining long-term customer context.
Key Characteristics
• Persist across all conversations with the same contact.
• Stored at the contact level rather than the session level.
• Suitable for storing information such as names, email addresses, preferences, lead status, and more.
• Can be updated at any time.
• The most recently saved value is always used.
• Enables personalized and context-aware customer experiences.
Example
If a user provides their name as "Pratik", you can save it in a Contact Variable. During future conversations, the bot can automatically greet them with:
"Welcome back, Pratik!"- without needing to ask for their name again.
3. Secrete Variable:
Secret Variables are used to securely store sensitive information such as API keys, authentication tokens, and credentials.
Key Characteristics
• Values are encrypted and stored securely.
• Secret values are never displayed in plain text.
• Once saved, the value cannot be viewed by anyone, including administrators.
• Existing values cannot be retrieved or read and can only be replaced with a new value.
• Can only be referenced within HTTP Request and JavaScript blocks.
Common Use Cases
• API Keys
• OAuth Tokens
• Webhook Secrets
• Authentication Credentials
• Third-Party Service Tokens
Example:
If you need to connect your bot to an external CRM or payment gateway, you can securely store the API key in a Secret Variable instead of exposing it within the bot flow.
Creating Variables from Variable Settings
To create a variable from the Variables settings page:
Navigate to Settings > Variables.
Click Create.
Enter the required details: • Variable Name • Description • Variable Type
Save the variable. All variables created within your workspace can be managed from this section.
Editing Variables
Go to Settings > Variables, then click Edit next to the variable you want to change.
Note: only the description and data type can be edited - not the name.
Deleting Variables
Variables can't be permanently deleted - they can only be archived.
To archive one, go to Settings > Variables and click Archive next to the variable you want to remove from active use.
Using a variable
You can invoke a variable by typing # to preview the variable dropdown across the bot builder
Example
If you have a Contact Variable called first_name, you can use it in a message such as:
"Hello #first_name, thank you for contacting us."
Adding default value to variables
You can add a default value to the variable, so that incase there is no value present a default value can be shown to the user. To add the default value, open the bot builder canvas, and click on the variable tag. You can then enter the fallback value.
Data types in variables
You can store the following type of data in variables:
Data type | Description |
|---|---|
Text | Stores any text input. |
Number | Stores only numeric digits from 0 to 9. |
Boolean | Stores only 0, 1, true, false. |
Date | Stores date formats as DD/MM/YYYY and MM/DD/YYYY |
Stores email addresses. | |
Phone | Stores phone numbers. |
Regex | Stores input based on your validation rule. |
Customizing Variable Error Messages
Improve your visitor's experience by replacing the default generic error ("Invalid! Please enter a valid input") with a custom, user-friendly prompt (e.g., "Please enter a valid business email address to continue").
Custom error messages are available for variables that use specific validation formats: Number, Boolean, Date, Email, Phone, and Regex.
How to set a custom error message:
Navigate to Settings > Variables from your left-hand menu.
Locate the variable you want to modify and click Edit.
Type your custom response into the Error Message field.
Click Save to apply the changes.
Test your bot flow to confirm the new error message displays correctly when invalid data is entered.
Retrieving JSON objects from a variable
If you are storing JSON objects into variables and want to refer to a particular field from the JSON object, you can follow the below approach:
Create a TEXT type variable
Store the JSON object in that variable
Use # followed by your variable name and append the field you want to refer to.
Hit enter so the variable chip is created
For example:
// Assume this is your JSON object
[
{ "account_id": "A1", "user": "John" },
{ "account_id": "A2", "user": "Sara" },
{ "account_id": "A3", "user": "Mike" },
{ "account_id": "A4", "user": "Tina" }
]
// If I want to refer to the second object i.e. account_id=A2
#name[1].account_id#System variables offered
Here are the system variables offered by default:
Variable | Description |
|---|---|
name | Name of the visitor |
Email of the visitor | |
phone | Phone number of the visitor |
ip_address | IP address of the visitor |
city | City detected through the IP address of the visitor |
state | State detected through the IP address of the visitor |
zipcode | Zipcode detected through the IP address of the visitor |
country | Country detected through the IP address of the visitor |
timezone | Browser timezone of the visitor |
os | System OS of the visitor |
referrer_url | Referrer domain to the visitor. |
unsubscribed_phone_numbers | Whether the phone number is unsubscribed from outbound messaging. |
utm_source | Utm source |
utm_medium | Utm medium |
utm_campaign | Utm campaign |
utm_content | Utm content |
utm_term | Utm term |
bot | Name of the bot the visitor interacted with. |
browser_language | Language set in the browser. |
browser | Name of the browser. |
channel | Name of the channel where the chat took place. |
contact_created_by | Who created the contact. |
conversation_url | Link to the conversation. |
country_code | ISO country code of the country where the chat originated from. |
created_at | Date when the chat was created. |
gcal_selected_slot_day | Selected day when booking the meeting on Google Calendar. |
gcal_selected_slot_time | Selected time when booking the meeting on Google Calendar. |
timezone | Timezone of the device. |
url | URL of the webpage where the user is interacting with the bot. |
chat_history | Includes the transcript of the conversation so far. |
Best Practices for Variable Management
To keep your workspace organized and ensure your bot flows are easy to build and maintain, follow these key best practices when creating variables:
Use Descriptive Names: Choose clear, intuitive names that immediately tell you what data is being collected. (For example, use “userEmail” or “orderTotal” instead of vague names like “var1” or “data”.)
Maintain Naming Conventions: Stick to a consistent format for all your variable names. This makes you easier to search, identify, and manage, especially when collaborating with a team.
Add Clear Descriptions: Take advantage of the description field to document exactly what the variable is used for and its specific role within your bot's workflow.
Regularly Review and Refine: As your bot scales and evolves, periodically audit your variables list. Clean up any unused variables and ensure the existing ones still accurately serve their intended purpose.