Botsquad documentation logo

In natural language processing, there is a difference between intents and entities. An intent captures a global meaning of a sentence: its intent, the thing that someone means. An entity, on the other hand, is a single piece of information. Intents might need one or more entities to do their work. Consider the following sentence:

“I want to book a flight tomorrow to New York”.

The intent here is “booking” – someone planning to make a trip. The “booking” intent here has two entities, “tomorrow”, which is a point in time, and “New York”, which is a location.

Intent triggers

As stated, an intent captures a global meaning of a sentence. For instance, the sentences “hello!”, “Hi there”, “How are you?” can all be seen as utterings of the same intent namely, a greeting.

In Bubblescript, intents are either matched using regular expressions (in the intent’s match: attribute), or using DialogFlow.

An intent which uses regular expressions can be defined as follows:

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

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

Intent triggers using DialogFlow

When DialogFlow support is enabled for your account, you can link any intent to its DialogFlow equivalent to enable the triggering of the dialog when an intent gets classified:

@greeting intent(dialogflow: "project.intents.greeting")

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

The intent.entities variable holds any entities that were matched as a result of DialogFlow’s intent classification.

Connecting your own Dialogflow agent

By default, Botsquad’s dialogflow intents are looked up in the default Botsquad agent. In order to connect your own Dialogflow agent, you need to connect your agent’s service account with your Botsquad bot.

In order to enable your own Dialogflow agent, follow the following steps:

  1. In Dialogflow, click the gear icon next to your agent’s name
  2. In the settings form that opens, ensure that you checked the V2 API tab. If not, check it, and click Save.
  3. Under the Google project section, click the “+” button in the table row that says Service account, to create a service account for your agent.
  4. Wait for a few seconds while Google creates a new service account
  5. The table now refreshes and shows a link to the service account (something like Click the link to open the service account.
  6. You are now taken to the cloud console. Click the three dots next to your service account and choose Create key.
  7. In the following dialog, ensure the “Key type” is set to JSON and click the Create button.
  8. A JSON file is now downloaded to your computer.
  9. Open the Botsquad studio and create a new YAML script. (“Add YAML file” in the add script dropdown menu). Name the script dialogflow.
  10. Empty the script file and paste the contents of the downloaded JSON file in the newly created YAML file.
  11. That’s it, any intents will now be queried on your own Dialogflow agent instead of the default Botsquad one.

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}"

Lastly, 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


The duckling option to entity() specifies that the integrated Duckling library will be used for the matching of the message.

Duckling supports extraction of various entities like phone numbers, email addresses, dates, et cetera.

@email entity(duckling: "email")
@time  entity(duckling: "time", locale: "nl_NL", timezone: "UTC")

Duckling matchers are locale and time zone sensitive. By default, the locale is en_US and the default time zone is Europe/Amsterdam.

Duckling extraction supports the following entities:

Matchers defined as entity() constants can be used as matchers in both dialog as well as ask:

@email entity(match: "[a-zA-Z0-9_.+-]+@[a-zA-Z0-9-]+\.[a-zA-Z0-9-.]+")
# alternatively use duckling:
# @email entity(duckling: "email")

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

dialog ask do
  entity = ask "What is your email?", expecting: @email
  say entity.value

The fields of the entity variable that Duckling returns are: