Variable Change Block

“Variable Change” Block

What is a “Variable Change” Block

The “Variable Change” Block is a data manipulation element in Grailgun that allows you to create, modify, and delete custom variables associated with bot users. Variables enable you to store and track user-specific data throughout the conversation flow, creating personalized and stateful bot experiences.

Main Functions

• Creating and updating flow variables for each user
• Storing user input and conversation state
• Setting static values or copying from other variables
• Supporting multiple data types (string, number, date)
• Enabling personalized dialogue flows
• Tracking user progress and preferences

Creation and Configuration

How to Add a “Variable Change” Block

1. Open the bot builder
2. From the Blocks panel, select “Add Variable”
3. The Block will be added to the workspace

Configuring Variable Change Parameters

1. Double-click on the “Variable Change” Block in the builder
2. Select which variable to modify (or click “Add Variable” to create a new one)
3. Choose an action to perform on the variable
4. Configure the value (if applicable)
5. Click “Save” to apply settings

Variable Types

Grailgun supports three types of variables:

String Variables

• Store text data
• Examples: user names, preferences, messages, identifiers

Number Variables

• Store numeric data
• Examples: counters, scores, ages, quantities

Date Variables

• Store date/time as timestamps in milliseconds
• Examples: last login, expiration dates, scheduled events

Variable Actions

USER_RESPONSE

Captures the user’s latest message and stores it in the variable.

Use Cases:

• Save user’s name when they introduce themselves
• Store user’s email address for later use
• Capture any user input for processing

Example Flow:

1. Message: “What is your name?”
2. (User responds: “John”)
3. Variable Change: Set “user_name” = USER_RESPONSE
4. Message: “Nice to meet you, {user_name}!”

CURRENT_DATE

Sets the variable to the current timestamp in milliseconds.

Use Cases:

• Record when user completed an action
• Track last interaction time
• Set future date calculations

Example:

• Variable Change: Set “last_login” = CURRENT_DATE
• Use later to check how long since last visit

STATIC_VALUE

Sets the variable to a specific value you define.

For String Variables:

• Enter any text value
• Example: Set “user_status” = “premium”

For Number Variables:

• Enter numeric value
• Example: Set “login_count” = 0

For Date Variables:

• Enter timestamp in milliseconds
• Example: Set “trial_end” = 1704067200000

Use Cases:

• Initialize counters
• Set default values
• Mark flags or states

COPY_FROM_VARIABLE

Copies the value from another variable.

Use Cases:

• Backup variable values
• Move data between variables
• Duplicate user data for comparison

Example:

• Variable Change: Set “previous_score” = COPY_FROM “current_score”
• Use to track changes over time

DELETE

Removes the variable and its value for the user.

Use Cases:

• Clean up temporary data
• Reset user state
• Remove sensitive information

Example:

• Variable Change: DELETE “temporary_code”
• Variable no longer exists for this user

Managing Variables

Creating New Variables

1. In the Variable Change Block form, click the “Add Variable” button
2. You’ll be directed to the Variables management page
3. Create a new variable with:
   • Name/Title
   • Unique ID
   • Type (string, number, or date)
4. Return to the builder and select your new variable

Using Existing Variables

• The Variable Change Block shows a dropdown of all variables for the current flow
• Select the variable you want to modify
• Choose the appropriate action

Usage Examples

Capture User Name

Scenario: Store the user’s name for personalized messages

Flow:

1. Message: “Hello! What’s your name?”
2. Variable Change: Set “user_name” = USER_RESPONSE
3. Message: “Welcome, {user_name}! How can I help you?”

Track Login Count

Scenario: Count how many times user starts conversation

Flow:

1. Variable Change: Set “login_count” = COPY_FROM “login_count” (backup current value)
2. Variable Change: Set “login_count” = STATIC_VALUE (increment by 1, using calculated value)

Alternative using multiple blocks:

1. Condition Check: Does “login_count” exist?
   • SUCCESS: Variable Change - Set “login_count” = USER_RESPONSE (would need calculation)
   • ELSE: Variable Change - Set “login_count” = STATIC_VALUE (1)

Record Activity Timestamp

Scenario: Track when user last interacted

Flow:

1. Variable Change: Set “last_active” = CURRENT_DATE
2. (Later) Condition Check: Is “last_active” older than 7 days?

Store Survey Responses

Scenario: Multi-question survey

Flow:

1. Message: “Rate our service 1-5”
2. Variable Change: Set “rating” = USER_RESPONSE
3. Message: “Any comments?”
4. Variable Change: Set “comments” = USER_RESPONSE
5. Message: “Thank you for your feedback!”

Reset User Progress

Scenario: Clear user data on request

Flow:

1. Message: “Reset your progress?”
2. Response Check: User says “yes”
   • SUCCESS path:
     • Variable Change: DELETE “progress”
     • Variable Change: DELETE “user_level”
     • Variable Change: DELETE “achievements”
     • Message: “Progress reset!”

Set Trial Expiration

Scenario: Give user 7-day trial

Flow:

1. Variable Change: Set “trial_start” = CURRENT_DATE
2. Variable Change: Set “trial_end” = CURRENT_DATE + 604800000 (7 days in milliseconds)
3. Message: “Your 7-day trial has started!”

Working with Variables in Messages

Variables can be used in Message Blocks using the syntax {variable_name}:

Example:

• Variable: “user_name” = “Sarah”
• Message: “Hello, {user_name}! Your score is {user_score} points.”
• Sends: “Hello, Sarah! Your score is 150 points.”

Tips and Recommendations

• Use descriptive variable names (e.g., “user_email” not “var1”)
• Create variables in the Variables page before using them in flows
• Choose appropriate variable types (string, number, date) for your data
• Use CURRENT_DATE for timestamps, not STATIC_VALUE with manual calculation
• Delete variables when no longer needed to keep data clean
• Combine with Condition Check to create dynamic flows based on variable values
• Use USER_RESPONSE carefully - it captures the entire message text
• Document what each variable stores for team collaboration

Frequently Asked Questions

What happens if I try to set a number variable with text?

The system will attempt to convert the value. If conversion fails, the variable may store unexpected data or remain unchanged.

Can I do math operations on number variables?

Not directly in a single Variable Change Block. You would need to use multiple blocks or use the HTTP Request Block with an external calculation service.

Where is variable data stored?

Variables are stored per bot user, meaning each user has their own set of variable values that persist across conversation sessions.

Can variables be shared between different bots?

No, variables are scoped to a specific flow/bot. Each bot has its own set of variables.

What happens if a variable doesn’t exist when I try to copy it?

The operation will fail, and the target variable will remain unchanged (or be deleted if it’s a DELETE operation).

How do I see current variable values for testing?

You can view user variable values in the bot’s Variables management page or through the testing interface.

Can I use variables in button text or URLs?

Yes! Use the {variable_name} syntax in any text field, including buttons, to inject variable values.