Botsquad documentation logo



The Botsquad studio contains a mechanism for non-technical users to edit parts of the bot, without them editing any Bubblescript code.

This chapter explains how data files can be used inside Bubblescript, how the various data file formats work, and how you can define basic CMS features to let people easily edit these data files.

Using constants for configuration

Often it is the case that your bot needs data for it to work. For instance, your bot might need some configuration settings, e.g. opening hours, a list of e-mail addresses that can be contacted, a general welcome text, et cetera.

There are several approaches how you could store these data.

You could “hardcode” them in your bot, e.g. like the following:

dialog check_time do
  if time > "18:00" do
    say "Sorry, we are closed right now."

But, when your opening hours change, you need to look in the code where you defined this. For this reason, we added constants, special variables prefixes with a @, which function as read-only constants.

@close_time "18:00"

# more code here…

dialog check_time do
  if time > @close_time do
    say "Sorry, we are closed right now."

This way, the logic is separated from the configuration.

However, the constants are still in the same file as the code. Wouldn’t it be nice if we had a way to define these settings on another place?

Data files

This is where data files come in. As soon as you create a data file, be it either a YAML, JSON or CSV file, these files get automatically exposed in the bot script as a @constant with the same name as the filename.

So it is possible to create a YAML file, for instance settings.yaml looking like this:

open_time: 9:00
close_time: 18:00

And then the variable @settings will be exposed in your script. Given that this YAML file is an object, it contains a @settings.open_time and @settings.close_time property.

The dialog becomes more simple:

dialog check_time do
  if time > @settings.close_time do
    say "Sorry, we are closed right now."

And the actual value of settings.close_time is stored outside the script.

Supported data types

The supported types of data are YAML, JSON and CSV.

Most of the time, you’ll find yourself using YAML: an easy to read and write file format which uses white space to define a data structure, with lists and objects. Watch a video explanation about YAML here.


JSON is the JavaScript Object Notation: a format mostly used by computers to interchange information. Use this data format if you have some external data that you want to statically incorporate in your bot, as-is. It is easy to make syntax errors with JSON, as it is picky with comma’s and quotation marks.

Hint: if you need to edit the JSON later, you might want to convert it to YAML first.


Finally, Botsquad supports CSV: Comma Separated Values, the format used by spreadsheets to present tabular data. When creating a CSV file, it is exposed in Bubblescript as an array of objects. The first line of the CSV file must contain the column names, and the comma (,) is used to separate the fields. Doublecheck this when exporting data into the studio; some programs use the semicolon (;) by default.

Say, you have the following CSV file, called users:


Then you can iterate over this in Bubblescript:

repeat user in @users do
  say "#{user.first_name} is #{user.age} years old."

Now that we know about data files, read on to learn about Content Management.