Skip to content

Migration to version 2.0

On July 1st, 2020, version 2.0 of the Botsquad platform has been released. Version 2 contains many improvements, especially around the area of Natural Language Processing. To support the introduction of the new natural language matcher (BML) we had to make some breaking changes. This document highlights those and providers pointers on how to address them.

  • String and Regular-expression based matches, in intents, dialog triggers and expecting: have been replaced with the new BubbleScript Matching Language (BML).
  • The answer and message user utterance variables now hold metadata (tokens, word_count, input_type, etc ) next to the utterance itself.
  • The intent and entity variable have been moved into the message variable.
  • When expecting an entity the entity's return value is now returned in answer.return

Automatic migration

As part of the deployment, we have automatically migrated all chatbots on our platform to address above changes. However, we have NOT published these changes to the BubbleScript code yet. Chatbots will be deactivated until their owner reviews the changes made by our migration bot and manually re-actives the chatbot.

If you need help with migrating your chatbot, do not hesitate to reach out to us. Use the chat button in the bottom right, or e-mail us at

As a chatbot developer, it is your task to review these changes and then publish the bot again to put it online again. When reviewing your chatbot take note of the following gotchas and auto migrations:

Regular expressions

Regexes have been automatically translated to BML. Where a regex matches characters BML matches words, entities and POS tags. Auto-migration used the following rules:

regex BML
^ start of sentence [Start]
$ End of sentence [End]
(.*) anything _ (max 5 words)
\\d+ regex /\\d+/ regex in / note double escape
#<name:regex> capture /regex/[=name]
\?\! punctuation punctuation is optional
(a |b )(c | d) groups (a|b) (c|d) spacing between groups

Following patters are both valid in Regex and BML with the remark that BML will match words (and apply stemming) where regex matches strings. This also means BML ignores whitespace by default.

  • word
  • word|word

The documentation contains a chaptor on BML where you can read more about the language and how test your expressions.

Expecting literal string

Expecting with literal strings used to match the exact string and automatically create quick_replies.

ask "Shall we continue?", expecting: ["yes", "no"]

In the 2.0 platform, the above syntax still works. However, under the hood it is interpreted as the following:

ask "Shall we continue?",
 quick_replies: ["yes", "no"],
 expecting: [intent(label: "yes"), intent(label:"no")]

Using the message and answer variable

The message and answer variables now hold more structued information. They are now a "struct" with the following fields:

# Any BML captures will go here
captures: {}

# data from form submissions
data: null

# whether the message was typed or touched (clicked) or spoken
input_type: touch

# if an intent matched this message, its intent struct is stored here
intent: false

# locale of the message
locale: en

# reserved for future use

# list of tokenized sentences
- text: 'yes'
  # list of tokens
  - end: 3
    index: 0
    raw: 'yes'
    start: 0
    type: spacy
    # spacy tokens contain metadata. See the BML documentation
      lemma: 'yes'
      norm: 'yes'
      pos: INTJ
      tag: UH

# various message statistics
  token_count: 1
  word_count: 1

# the literal text
text: 'yes'

# the type of message
type: text

Although answer and message are a struct now, these variables still behave like they are a string when they are used in say, and in functions that expect a string input.

ask "Shall we continue?", expecting: ["yes", "no"]
if answer == "yes" do
    say answer + " is the correct response"

So in most cases the use of answer and message as string still works and no migration is required. To convert a struct to a string explicitly, use the new string() builtin function.