Skip to content

Variables & Constants

Variables

Variables in Botsquad script can be global and local, meaning they are available from anywhere in Bubblescript or they are only available in the current dialog. Some variables are made available by the system, others are created by the user in the scripts by assignment. All variables are can be seen in the panel below the script editor.

  user.id
  user.frontend
  user.first_name
  user.last_name
  user.presence
  ...

Variables that start with user. are special in that they are saved inside the user record the bot keeps. Note that these are shared between all conversations between a user and the bot. Those user variables are also automatically added to the CSV export in the contacts section of the studio.

Global and local variables

Every variable that starts with a "_" is considered a local variable. This means that the variable only exists within the dialog or task it was created in. It's value is stored even if another dialog is invoked in the mean time, but the other dialog won't have access to that variable, the same is true for tasks. Local variables are great when they are combined with repeat loops and conditionals. They can have a name that represents what they stand for without having to worry that a global variable might be overwritten.

Predefined variables

Some variables are set (when triggered) by the runtime itself:

  conversation
  message
  answer
  location
  attachment
  event
  user
  bot
  schedule_id
  session_id

Don't set these reservered variables yourself as they will be overwritten!

Variable types

The variable types that can be used in Bubblescript are similar to the variables in Elixir, please visit the link for an in-depth explanation. Any reference in their documentation to the word "iex" is similar to a line typed in Bubblescript.

String

A string is text and is always typed in double quotes ("). If you want to use double qoutes in your string, you should escape them in the following manner: "this string contains \"double quotes\"".

Strings interpolation

Strings can be interpolated by adding #{variable_name} in the strings themselves. What this means is that the value in the variable will be added to the string. Think of this as the "find and replace" function in a text-editor. This is useful for creating pieces of text that function as templates for responses or questions.

Examples:

dialog greeting do
    name = ask "What is your name?", expecting: @text
    say "Hi #{name}"
end

Accessing nested values

The following example shows how the value of a Map is displayed by using the key in string interpolation.

user = %{"name" => "Hank"}
say "Hello #{user.name}"

The . notation used here is the same way a key of a Map is accessed.

List

A list can be seen as a sequence of things, where these things can be strings, maps, or other variables. To get the first item in a List you can use the bracket notation [0] Note: List like arrays in most programming languages start at 0 zero!

list = [1, 2, 3]
say list[0]         # 1
say length(list)    # 3

To iterate over the full array you can use repeat:

dialog iterate do
  list = [1, 2, 3]
  repeat element in list do
    if element == 3 do
      say "and.."
    end
    say "item #{element}"
  end
end

Map

A Map is a key->value data structure that allows a value to be stored in with a key. If we would like to see the value, the key is our reference point with which we can find the value.

simple_map = %{"name" => "Bert"}

numbers_as_keys = %{1 => "one",
                    2 => "two"}


# Here we create a map that will describe a car

car = %{"brand" => nil,
        "engine" => %{}} # notice that the value of a map can also be another map.

Note that you can create these maps yourself as well:

  car.brand = "Volvo"
  car.engine.hp = 200

  # car == %{"brand" => %{"engine" => %{"hp" => 200}}}

Autovivification

If a key is not found in the map when you assign it in the map, it will be automatically be created for you. In the example above, when 200 is inserted in the key hp the preceding map engine will be created automatically.

Constants

Variables starting with an @ are treated as constant values. These can only be defined outside a dialog.

@constant "key"
@version 12
@message "Hello and welcome!"

dialog main do
  say @message
  say "My version is: " + @version
end

notice that you do not need to use an assign (=) character for assigning values into a constant!

Platform-specific constants

The following constants have special meaning, when they are defined.

  • @timeout - defines how long the script will be allowed to run before it times out. When the script times out, the next time the user interacts with the bot, a new session is started (starting again in the main dialog).
  • @delay - defines the standard delay (in seconds) after the bot shows a message to the user
  • @typing_indicator - defines the standard delay (in seconds) how long the typing indicator should be displayed before any message is shown to the user.
  • @ask_timeout - defines how long to wait for a user to give an answer on a question (ask)

Example:

@ask_timeout      :infinity
@timeout          "15m"
@delay            1
@typing_indicator 1

# Other time formats
@timeout "1h"
@timeout "60s"
@timeout "200ms"

Besides these globals that can be overwritten there are some read only globals that you MUST NOT ovewrite:

  • @intents - is a list of all intents defined in the intents files (read only)
  • @skills - is a list of the skills (modules) this bot has (read only)

Note: the intents and data files you creata also create constants that can conflict with these system contstants. So don't create an intent or data file with the name skills or intents

Intent constants

When you create new intents via the training panel or directly in the training yaml file they will be exposed in the code as constants. So the @yes constant refers to the yes intent.

Loading constants from a file

When adding a YAML or a JSON file in the Botsqud studio, the contents of that file is exposed in a constant which is named after the JSON/YAML script file name.

Data files are a convenient way to keep data outside the bot script contents, but still embedded as part of the bot.

For instance, when you create a YAML file called people with the following contents:

- name: Arjan
  age: 38
- name: Pete
  age: 22
- name: Julie
  age: 32

The contents of the people file is now accessible in your bot script under the constant @people. It can be used like this:

repeat person in @people do
  say "Name: " + person.name
  say "age: " + person.age
end

When a data file is defined in a folder, say, a data file named data/people, the slash in the filename will be transliterated into an underscore, so that in this case, the constant name becomes @data_people.

Read more about data files and content management