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.
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.
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
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:
Using variables in an answer
Customizing AI agent messages
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
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.
14 comments
Marcin Rogalski
Hi. This looks like a good starting point to get our bot to work for transferring to agents when online but leaving a message when they're not. Though I don't see any options for variables. We only see School Name and Email. No external and no data condition variables. We want to be able to add business hours or whether the account or a group is online.
Where is this added? Thanks Martin
0
Marcin Rogalski
How do you actually add the variables? Seems like there would be some predefined ones based on values in your account. Like online status or ticket status, etc.
3
Florian Wallny
Hi, is it possible to store an array received from an external endpoint as variable? Can i make the bot output an array of strings as multiple messages?
0
Julio H
To be able to see variables, these variables must be asked to the customer in the ask for details steps or via other steps like the API call, to get external data or Messaging metadata variables, when using JWT.
The ask for details step, only supports dropdown and text fields.
You can specify directly in the flow the business hours with the step called Business hours.
Unfortunately, it is not possible yet to show or use as a variable what group is online.
I've marked this conversation as product feedback for review, which means that your input will be aggregated as a part of our Voice of the Customer program that provides customer feedback to our product development teams.
In addition, I encourage you to create a new post in the General Product Feedback topic in our community to engage with other users who have similar needs and discuss possible workarounds. Conversations with a high level of engagement ultimately get flagged for product managers to review when they go through roadmap planning.
Specific examples, details about impact, and how you currently handle things are helpful for our product teams to understand the full scope of the need when working on solutions. You may also want to review the Product feedback guidelines and how to write an effective feedback post [https://support.zendesk.com/hc/en-us/articles/4413820079386-Giving-Product-Feedback-at-Zendesk-].
We truly value customer feedback and your voice and votes in the forums help influence future Zendesk functionality.
0
James Molina
How would one use user field values as variable options?
0
Neil
There isn't any specific instructions on how to use a user field as a variable at the moment. But you can testing by using External service variables which allows the use of REST API to pull data (Make API call), in your case User field API.
0
Gupy Central de Ajuda
Hello!
I'm wondering if I can use variables to personalize my WhatsApp Bot. I already built the flow with the needed variables so I can customize the answers.
0
Viktor Osetrov
I have checked on my test account using my WhatsApp Bot. Unfortunately, variables don't work at this moment. Apologies for that - it looks like product limitations.
The possible solution is to upgrade your bot with Sunshine Conversations. Please read more about - Adding Sunshine Conversations channels to the Zendesk Agent Workspace.
Thanks
1
Fernando Rocha
If anyone is wondering how to create/add variables, you must make a request to the API first (at the bot builder there's a button to test the request) and only when you get the response you can "save" the response fields as variables.
Beg your pardon, mine is in portuguese but the UI stands the same.
then hit "save" on the API field you want to save
And this is working on WhatsApp
1
Theodore Cooke
With our current chat bot, we have a script that runs on the web installation that injects variables into the conversation so the bot is aware of the user's geolocation, device type, and a few other things. Is it possible to do likewise with these bots? Can we have our frontend pass in variables to the bot?
0
Dane
Please check Saving variables from the API response.
0
Cedric D.
I can't find how to use the user language to propose relevant articles URL in a Carousel step in the builder.
I tried to workaround with building a “greetings” answer which will collect a custom field “spoken_language” thanks to “ask tor details”. After the greetings I planned to redirect the user to another answer to read articles.
The problem I face is that the custom field collected in an answer is not kept in another one !
If at the greetings step I collect a Name, it is kept in another answer which will transfer to an agent (the name is displayed in the ticket).
Thanks for your help
0
Andrew
Hi, Will we get dynamic templating support? I want the end user to select a dropdown, then have that dropdown set a dynamic block of text, without being forced to branch my entire flow and multiply maintenance work (I'm already running up against the 2000 node limit).
For example, if they pick from a set of office locations, they get a different email and phone number.
0
Sai Karri
How to add variables as tags in the transfer step to auto-populate the respective custom dropdown field I user in the agent form (in the workspace) for handling the tickets
0