In the custom rules of an interaction, you can assign various data points to either slots or variables. Both are useful in API integrations.


Variables are the default way to store and access important data points throughout the flow of a bot.

System variables

There are several system variables that store information that's commonly needed in use cases. You can use these variables in your interactions:

  • {$chatBotId} - Returns the ID of the bot.
  • {$chatBotUserId} - Returns the ID of the user (the consumer).
  • {$chatBotUserPlatformId} - Returns the ID of the bot user agent. This is provided by Conversational Cloud.
  • {$conversationId} - Returns the ID of the current conversation. This is provided by Conversational Cloud.
  • {$firstname} - Returns the first name of the bot user agent. This is provided by Conversational Cloud.
  • {$quickReplyPayload} - Returns the quick reply payload for the current interaction.
  • {$userMessage} - Returns the current user message.

Storing user responses

The most common use case for variables is storing user responses to questions.

Frequently you will want to capture what was just said by the user as the value of a variable. You can use {$userMessage} to do this, for example:

You can also use {$query} in the same way; it works like {$userMessage}.

Storing and accessing variables with code

The Get and Set Bot Variables functions can be used to store and access variables in the Pre-Process / Post-Process Code or the Process User Response JavaScript code panels.

Cleaning variable data

Before setting or storing data in a variable, in the Process User Response code, it's a good idea to "clean" or "sanitize" the data by parsing it and transforming it to remove problematic issues, i.e., remove leading or trailing white space, remove new lines ( \n ) and special characters, and so on.


Slots are a special type of variable. Most of the time, you will use variables to take what a user says and hold on to it for later use. Slots are useful for more specialized use cases.

Slots & entities

When combined with entities, slots bring dynamic, fluid behavior to storing user input data.

For example, if you add a question interaction "what type of shoes are you looking for?", the Assist tool will suggest appropriate entities and slots for that interaction. As long as the user stays within the bounds of entities that you have created, slots will automatically adjust and update based upon user input throughout the conversation.

Adding a slot

To configure a slot, select the interaction where you'd like to look for entities in the user's input (like a multiple choice question, for example). Then add a custom rule. In the Add Next Action Rule dialog box, click +Add Slot.

Enter a slot name. We recommend using standard naming conventions for slots. The slot name is later used to refer to and access the data that the slot contains. Then, for the value field, look for a pre-configured entity (which you should have set up for your domain previously) by typing in first the "@" character and then the name of your desired entity. Lastly, decide how long you'd like the slot's data to be kept for, i.e., the duration.

{$botContext.slot.slotName} is how you can access values in slots and use them in other ways. For example, to have the bot respond with a user's previously stored answer under the assigned entity animal, you'd set up a text interaction like so:

"You answered: {$botContext.slot.animal}!"

If your bot asked the user "which animal do you like?" and the user answered "dogs" or something similar, the slot for the entity animal would be populated with their answer. The bot would then respond with "You answered: dogs!" populating the code above with the user's reply.

Slot filling with multi-entity extraction

Slot-filling becomes especially useful when mining the entities that make up a user's intent to pre-populate your list of questions, and streamline the data collection process.

  1. Create a new dialog and associate an intent from your domain as the dialog starter. For this example we will create the dialog ordering with the domain intent order item.
  2. Now, devise a few entities that will be captured in our intent. For this example, we are going to create an entity for color with the values blue, white, and red, one for item with pants, shoes, shirt, underwear. and finally, one for size with the values small, medium, and large. Before moving on, update and train the order item intent with some representative training phrases that contain these entities.
  3. Next we will create the questions our dialog will ask. You should add one question interaction per slot that you are looking to fill. Using Assist, assign your entities to the relevant questions, for example:

    Once completed you will have a list of questions that looks like the following:

    When you assign an entity to a question, this automatically creates a rule for each question. Each rule creates a slot that contains our slot variable (e.g., item) and whose value is the entity value (e.g., @item).

  4. Now you can test the bot using an intent with slot choices as part of the query. When you enter the dialog, if a user has supplied an entity that is known to the domain, it will automatically populate the slot and skip the interaction and move on to the next interaction's question.

If a user manages to express all the slots as part of their intent query, it will skip to our confirmation step.

When to use variables vs slots

Variables are the default storage unit of Conversation Builder, while slots are a special type of variable. The only reason to favor slots is if you need extra functionality that is linked to entities or if entities will be used in an API Integration catalog search, for example.

When in doubt, it is best to use variables. The Assist tool will help to display when slots are most useful.

Duration of variables and slots

When you define a variable or slot, you specify how long to keep the stored data.

There are three options for the duration:

  • Request: The data will be saved for that particular use of the variable or slot. This option is only useful if the next question in the tree depends on the data.

  • Dialog: The data will be stored for the specific dialog. Once the dialog ends (either by the consumer closing the conversation or the bot switching to a different dialog), the data will be cleared.

  • Session: The data will be saved for the entirety of the consumer's automation session. This is useful when using the data to query APIs and retrieve information that might be useful across the entire bot.

If you need to store data for the long term, use the Conversation Context Service.

Using variables and slots in interactions

{} is used for inserting dynamic values inside of interactions: