Botscript is a core component of Zenbot. It is like a program for your bot - it contains all data about dialog branching and all actions which Zenbot must perform.

  But don't worry - you do not have to learn any programming language to create Botscripts.

Zenbot “eats” Botscript as an input and builds a bot from it. You can manage different versions of the same Botscript on your side (by using Github repository for example) while Botscript is a set of regular XML files.

Git repository

Once you have created a new bot, you have to define your Git repository settings. Zenbot automatically builds and deploys your Botscript once you have committed any changes.

This can be done for example with Github or Butbucket (the last one has a free private repositories). Here is a comprehensive tutorial about Github and Git that helps to start working with Git repositories.

  Pleas note that you can host multiple Botscripts in a single repository. Just define the working directory in your Repository settings in Zenbot web console to specify the Botscript directory.

Botscript format

Botscript is a set of simple XML formatted files. You can use any favorite text editor to create it.

Just take a look at a very simple Botscript to have an idea about what it is.

<context>
  <input pattern="(hi|hello) *">
    <output value="Hi!"/>
  </input>
</context>

  You can find a similarity with well known AIML here. But of course Zenbot provides much more powerful and flexible tools and has different paradigm. Read more further.

How you can see, this simple Botscript responds with “Hi!” text on every phrase which starts with words “hi” or “hello” and ends with any other words.

So such bot will react on such phrases as “Hello”, “Hi” or “Hi there!”

Nothing difficult! But there was a really simple one. Zenbot can understand much more complex Botscripts which contain dialog branching, context switching, variables persistence and even HTTP requests and Javascript code evaluation.

  Try to create a file with this Botscript and upload it through Zenbot's web console to your first test bot. It is a good idea to learn how it works on a practice.

Multiple files in Botscript

You are able to compose a Botscript from multiple files instead of pile everything into a single one. To do this just create a set of XML Botscript XML files. Zenbot will automatically merge it in a single bot.

Please note that you have to pay attention for “order” attribute in “context” tag to resolve dependencies between files. Read more in context tag article

Botscript concepts

You have to understand some basic principles of Botscripts to be fluent with Zenbot.

Each Botscript contains a set of nested contexts, inputs, outputs and some other tags to describe the bot's logic.

Context

Context in terms of Zenbot looks like a dialog context in the human communication.

We all know that we understand each other not only because we talk on the same language. We also share the same context - a set of “valid” phrases at this moment.

Each context in Zenbot contains a set of inputs (valid phrases) and set of actions Zenbot has to perform once the user says something that matches with this input. It also can contain nested contexts to implement dialog branching. Let's look at this example which greets a user.

<context>
  <input pattern="(hello|hi) *">
    <output value="Hello $UserName!" if="full($UserName)"/>

    <context if="empty($UserName)">
      <output value="Hi! What is your name?"/>

      <input pattern="$Text">
        <var name="UserName" value="$Text" scope="user"/>
        <output value="Nice to meet you $UserName!"/>
      </input>

    </context>
  </input>
</context>

Well, it is a bit more complex than the first one but we can understand it easily.

Such bot will greet a user if it knows her name. Otherwise bot will activate nested context and return a question “Hi! What is your name?”

This nested context has a simple input which accepts any text and interprets it as a user's name. Then it stores this text as a user's name in Zenbot's database and greets the user with phrase replacing “$UserName” placeholder with actual user's name.

As you can see, Botscript provides a powerful way to control dialog flow, cen operate with entities fetched from user's phrase and evaluate some sort of conditions.

  This Botscript contains some other components like 'if' and 'scope' attributes. Do not pay much attention to it at this point.

Read more about context tag in this chapter.

Input

Input tag contains a set of phrase patterns which are valid for this context. The example above shows an inline mode of the input tag with one pattern per input. But of course input can contain a set of patterns, like so:

<input>
  <pattern value="(potatos|tomatos)"/>
  <pattern value="(raspberry|razz)"/>
</input>

Each time Zenbot processes a text input, only one input can be selected - those where one of nested patterns is matched with request better.

Input can also contain a set of actions to perform and a set of outputs to return. Thus Zenbot know what to do and how to answer to the user's request when particular input is activated.

Read more about input tag in this chapter.

Pattern

Pattern tag is a core of Botscript. It contains a pattern of valid user's phrases. Otherwise we have to enumerate all possible phrases in a long-long list for each input… Do we like it? I guess no. So patterns eliminate this problem with ease.

  You can think about patterns like about regular expressions but much more adopted to the natural language.

Pattern is a very flexible tool to describe valid phrases and custom entities. It is much more powerful then all of those examples we have already seen. You can express a very complex patterns with usage of alternatives, options, repeats, wildcards and other stuff.

There is a special chapter about pattern syntax in this documentation.

Patters can also be included inside a context. In such case it become the custom patterns which can be used inside another patterns and so on. This helps to make a reusable set of patterns in your Botscript.

Read more about pattern tag in this chapter.

Output

Well, your bot has to respond somehow on the user's input. Otherwise what is it created for?

  Strictly speaking you do not have to define output tag. In such case your bot will not respond with any text on the particular input.

Output tag is designed exactly for this. It generates some text output when parent input or context has been activated.

As an input tag, output tag has inline (we have seen it before) and default format. Let's look at this example:

<input pattern="(hi|hello) *">
  <output>
    <item>Hi!</item>
    <item>Hello!</item>
    <item>Good morning $UserName!</item>
  </output>
</input>

Zenbot will randomly select one of item inside the output tag and replace all placeholders with actual values. Thus your bot will respond as a human - with different phrases on the same request.

Read more about output tag in this chapter.

Samples

Your bot can also respond with a set of samples which can be rendered as buttons by the particular messenger (like Facebook Messenger, Slack an etc.) This tag helps to generate such set of buttons with a simple lines:

<input pattern="(hi|hello) *">
  <output value="Hi! What is your favorite color?"/>

  <context>
    <sample>
      <item>Green</item>
      <item>Blue</item>
      <item>Red</item>
    </sample>
    <input pattern="* $Color *">
      <output value="Nice! I like it too!"/>
    </input>
  </context>
</input>

Once the user clicks one of the rendered buttons, your bot will receive a text of this button as a regular input, as if the user has typed it manually.

Please read more about sample tag in this cahpter.

Other Botscript's features

Of course Botscript provides much more features like variables, custom entities, HTTP GET and POST requests and even Javascript code evaluation. You can read about all of them the corresponding chapters.