Skip to content

Bubblescript integration

Intents usage

To use an intent in Bubblescript that was defined with the intent manager, we have to know its identifier, the name that you gave it while defining it.

Each intent that is created in the intent manager is exposed in Bubblescript as a constant, based on its identifier. For instance, if we defined an intent named greeting, the constant name that we can use is called @greeting.

The Botsquad studio warns you when you use a constant that is undefined, so that's how you know that you are using the right constant name for the intent.

Now, if we want to use @greeting, we have two options:

using a dialog trigger

Use the trigger: construct of the dialog to make a dialog that starts when the user types something that matches the intent:

dialog trigger: @greeting do
  say "Hello to you too!"

using ask with expecting:

When using ask, you almost always want to use expecting: to ensure that the user types something that is in the logical path of the dialog. Defined intents can be directly used in ask; the ask will "block" until the expecting clause is satisfied.

dialog main do
  ask "Please, greet me, will you?", expecting: [@greeting]
  say "Hello to you too!"

Using an intent this way, the label of the intent (when defined) will show up as a quick reply:

all intents

The list of all intents that are defined using the intent manager, is accessible using the @intents constant. Note that any programmatically declared intents (see next section) are not listed in the @intents list.

Programmatic declaration of intents

Besides managing intents through the intents user interface, they can also be declared directly inside Bubblescript files. To declare an intent which uses plain string matching, you would write the following:

@greeting intent(match: ["hi", "hello there", "howdy", "hello", "hey"])

dialog trigger: @greeting do
  say "Hello to you too!"
  log intent

This code first declares the intent, and the defines a dialog that gets triggered when the intent is matched agains the user's input.

Note that the intent variable is filled whenever a dialog is triggered due to an intent match. The intent variable contains relevant information like entities and a confidence score.

Entity extraction

The entity builtin defines a matcher which can be used for fuzzy matching in user input and in message triggers. The result is an extracted "entity" - a part of a the string, possibly normalized in a generic format.

@yes entity(match: "yes|yep|sure", label: "Yes", return: :yes)
@no  entity(match: "no|nope|nah", label: "No", return: :no)

@yes entity shows the label "Yes" in the quick replies, returning the atom :yes on match. @no shows the label "No" in the quick replies, returning the atom :no on match.

@postcode entity(match: "[0-9]{4}\\s*[a-z]{2}")

Creates an entity extractor which matches on a regular exression.

Entity usage

Entities can be used in the ask statement, to directly match something and return the value. Entities can be passed in the expecting: construct of the ask statement, and the ask then blocks until (one of) the given entit(y)(ies) has matched.

@number entity(match: "[1-9][0-9]*")
dialog main do
  age = ask "What is your age?", expecting: @number

Like intents, entities can also be used as dialog triggers as well:

dialog trigger: @email do
  say "Thank you for your email! You entered: #{entity}"

Entities can be extracted from arbitrary strings using the extract_entity() function:

@postcode entity(match: "[0-9]{4}\\s*[a-z]{2}")

dialog extract_entity do
  sentence = "My postcode is 1061BM now"
  entity = extract_entity(sentence, @postcode)
  say entity.value

Lastly, entities can also be extracted by using multiple matchers and values in one entity:

@colors entity(match: %{"red" => 1, "green" => 2, "blue" => 3})

dialog extract_entity do
  ask "What is your favorite color?", expecting: @colors
  log answer

In that case, when a user enters "red", the answer variable will be filled with the value 1, when they type "green", it will be 2, et cetera.

Next up: A special type of intents are Duckling intents, read on to find out more.