Using variables to personalize AI agent answers (Legacy)

What's my plan?

Suite

Any plan

This article describes functionality available only to customers who had a drafted or published AI agent as of February 2, 2025. For information about equivalent functionality in the AI agents - Advanced add-on, see Building dialogues for AI agents - Advanced.

In the bot builder, a variable is a container for data related to a conversation, such as a customer's name or a store order ID. During a conversation, an AI agent for messaging can utilize variables in many ways, including:

• Inserted into AI agent messages to personalize text responses, display dynamic information and images, or branch the conversation.
• To set a value for a variable based on an end user's input.
• In tags that are added to tickets during the Transfer to agent step.

An AI agent can include up to 46 unique variables across all answers. Each unique variable can be used in an answer as many times as needed.

This article includes the following topics:

• About variable names and values
• About variable types
• Using variables in an answer
• Using variables in tags

About variable names and values

In the bot builder, each variable has a name and value. When configuring a step in an answer, the name acts as a placeholder for the value. When the AI agent runs the answer, it replaces the variable's name with the variable's value. For example, you can use a variable named Email as a placeholder for the customer's email address.

Note: Only the first 280 characters of a variable's value appear in the response displayed in the messaging conversation.

Variables are global within an AI agent. After they're created, variables are available in all subsequent answers in the end user's conversation via free text or the Link to another answer step.

Handling empty variables

A variable is empty if it has no value. AI agents skip empty variables during a conversation.

For example, a Send message step include an AI agent message of "Your package's shipping status is shipping_status." If the shipping_status variable is empty during a conversation, the AI agent sends "Your package's shipping status is ."

AI agent message	Customer view

Handling missing variables

In the Make API call step, if one of the saved variables is missing from the response, the step's Fail branch is triggered. See Using the Make API call step in bot builder (Legacy).

About variable types

Bot builder organizes variables based on how they're created and the data they store:

• Customer variables
• External service variables
• Messaging metadata variables
• Sunshine conversations variables

Customer variables

Customer variables store information provided by a customer during an Ask for details step. For example, the step may ask a customer to provide their name and email address.

When inserting a variable in a step using the Add a variable icon () , customer variables appear under Responses from customer.

External service variables

External service variables store data received from an external system during a Make API call step. For example, the step can make a REST API request to a shipping provider to fetch the current status of a package.

Admins create external service variables when configuring the Make API call step. As part of the configuration, the admin can set a custom name for each variable.

When inserting a variable in a step using the Add a variable icon ( ), external service variables appear under Responses from external service.

Messaging metadata variables

Messaging metadata variables contain information about a customer's identity and authentication status. Messaging metadata variables get their values from the signed JSON Web Tokens (JWTs) used for messaging authentication.

Messaging metadata variables aren't enabled by default and are only available for the Web Widget and mobile SDK channels. For more information about enabling and using messaging metadata variables, see Using authentication metadata in an AI agent answer.

If enabled, messaging metadata variables appear under Messaging metadata when inserting a variable in a step using the Add a variable icon () ,

Sunshine conversations variables

Sunshine conversations variables can be used to connect to your Sunshine Conversations integrations.

Available variables include:

• SunCo user id
• SunCo conversation id
• SunCo app id

Using variables in an answer

With the bot builder, you can use inserted variables to:

• Customize AI agent messages
• Send data to external systems
• Branch an answer's flow
• Set variable values

Customizing AI agent messages

Admins can insert variables to the AI agent message of the following step types:

• Present options
• Add carousel
• Transfer to agent
• Send message
• Show help center articles

For example, the following AI agent message includes the Name variable.

Sending data to external systems

When making a REST API call to an external system using the Make API call step, admins can add insert variables into the path and query string of the step's Endpoint URL field. For more information, see Using the Make API call step in the bot builder.

Branching an answer's flow

The Branch by condition step lets an admin branch the flow of an answer based on the value of one or more variables. For more information, see Understanding branching conditions.

Note: Custom drop-down ticket fields use the Tag value as the variable’s value.

Setting variable values

Admins can use the Set variable step to create a new variable and assign a value or to select an existing variable and overwrite its value based on an end user's actions in a conversation. Variables can be referenced across all answers in the AI agent.

See Understanding answer step types: Set variable for usage details.

Using variables in tags

Admins can use variables in the tags that are added to a ticket created as part of the Transfer to agent step. These tags can be used by agents to view, organize, and track tickets, and in automated actions such as ticket routing and other business rules.

Although they are technically part of an answer, variables in tags are subject to some rules and restrictions that other variables aren’t.

You can use variables generated from API calls and system variables. Available variables appear in the selection drop-down:

However, variables containing input from end users can’t be used in tags. They will appear in the drop-down list but will be disabled. For example, you can’t refer to a variable using information collected in an Ask for details step earlier in the conversation.

The following rules and recommendations apply to using variables in tags:

Character limit

• Hard-coded tags are limited to 80 characters each.

Special characters

• Variables containing the following special characters can't be used and won't appear as available variables: £, `, ´, \, [, ], {, }, (, ), <, >, %, &, ?, +, @, !, *, $, #, =, and "
• Space or commas used in variables appear as underscores in tags.

Additionally, we recommend the following best practices when using variables as tags:

• Tags are typically used for routing conversations or in trigger conditions. If you want to add information to tickets for agent context, we recommend using custom fields.
• Limit the number of possible values for a variable. Too many values can cause unexpected behaviors.
• Keep value options short to avoid having them truncated as tags.
• Avoid having special characters in the values.