Triggers & Responses

RiveScript Documents

RiveScript documents usually contain several lines. Each line begins with a command character, and each command character is followed by text that means something based on the command.

Lines can be indented (have spaces or tabs on the left side before the command character).

Vocabulary

RiveScript

This is the name of the chatterbot scripting language.

Interpreter

This is the software program that knows how to read and execute RiveScript documents.

RiveScript Document

As explained above, this is a text file that contains RiveScript code.

Command Character

A command character is a symbol that appears at the beginning of a line of RiveScript code that tells the interpreter how it should process the rest of the line. These are always symbols and not letters or numbers.

A Simple Example

For this example, you'll need to know about two of the most common RiveScript command characters: + for triggers that match the human's message, and - for how the bot responds when the human matches that trigger.

First we'll try out the following code, and then discuss these two command characters in more detail:

+ hello bot
- Hello human!

All the code samples you'll see in this tutorial will be followed by a "Try Online" link. You can then just click the "Execute" button on that page to run the code already provided, or edit the code first.

After clicking on the Execute button, say "hello bot" in the chat window. The bot should respond by saying "Hello human!"

You might notice that if you say anything else besides "hello bot" here that the bot will respond with "ERR: No Reply Matched" - this is because there is only one trigger and it only matches if you say "hello bot". If you say something else, no triggers match what you said, so you get this error in response. When we cover wildcards you'll learn how to provide a catch-all trigger that will match the user's message if nothing else does.

Now to explain these two commands you used:

+ Trigger

If you use any uppercase letters or invalid symbols in the trigger it is considered to be a syntax error. If you try this in the Try Online web editor, it will give you an error and kill your current session, forcing you to reload the page in your browser.

Consider the following examples of triggers:

+ hello bot

+ how are you today

+ do you know who i am

// This trigger causes a syntax error:
+ who am I?

Did you notice the // above the fourth trigger? That is a comment line. When two slashes (//) are found in a RiveScript document, the interpreter ignores everything to the right of those characters. So, you can use comments on their own line like shown here, or you can use them next to another line, like this:

// This is the simple trigger again
+ hello bot    // What the human says
- Hello human! // How the bot responds

Comments are completely ignored by the RiveScript interpreter.

- Response

Unlike the Trigger, the Response doesn't have very strict syntax. You can have any text you want in the Response, including symbols and punctuation.

If there is more than one Response for the same Trigger, it causes the response to be chosen randomly out of all the Responses. In this example, the bot will say something different -- at random -- when the user says "hello bot".

+ hello bot
- Hello human!
- Hello!
- Hi there!
- Hey!
- Hi!

Now if you say "hello bot", it will pick one of those replies at random. If you say "hello bot" again, it might say something different than it did the last time.

Weighted Random Responses

You can assign weight to a response by inserting the {weight} tag. You can place this tag anywhere you want in the response, but putting it at the beginning or end is the most common. Here is our last example again but with using the weight tags:

+ hello bot
- Hello human!
- Hello!{weight=5}
- Hi there!
- Hey!{weight=5}
- Hi!{weight=10}

Here, the responses "Hello human!" and "Hi there!" don't have weight tags. A trigger with no weight automatically has a weight of 1! Instead of having to write {weight=1} on these triggers, we can just leave them off.

The most common response given now will be "Hi!", followed by "Hello!" or "Hey!" (they both have the same weight), and the least common will be "Hello human!" or "Hi there!"

So what are the odds of each reply given? To find out, just add all the weights together (keep in mind that those without explicit weight tags have a weight of 1). The weights here add up to 22, so the odds of each response being chosen:

Hello human!  -  1/22
Hello!        -  5/22
Hi there!     -  1/22
Hey!          -  5/22
Hi!           - 10/22

In the next chapter you'll learn about other things you can do with the Trigger tag.

Up: Table of Contents
Next: More About Triggers