Triggers & Responses
RiveScript Tutorial

Triggers & Responses

RiveScript Documents

A RiveScript Document is a text file, created in a text editor such as Notepad, that contains RiveScript code. These files can be created and edited in any text editor on any operating system.

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).


You'll encounter the following vocabulary as you read through this tutorial:
This is the name of the chatterbot scripting language.
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

Let's get started with RiveScript by trying out a simple example. For all the examples in this tutorial we'll be using Try Online, a web-based service that allows you to write and test RiveScript code directly within your web browser, without needing to install any software on your computer.

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:

A Simple Example
+ hello bot
- Hello human!
¤ Try Online

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

The plus symbol (+) command tells the interpreter about a pattern to use for matching the human's message. The pattern is all lowercase, containing only lowercase letters and numbers. Additionally some meta characters may be used: ( | ) [ ] * _ # @ { } < > =. These characters will be explained later in the tutorial.

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:

Trigger Examples
+ hello bot

+ how are you today

+ do you know who i am

// This trigger causes a syntax error:
+ who am I?
Why does the last trigger cause a syntax error? Two reasons: the capital letter I, and the question mark. Triggers must be lowercase; if you want to use the letter I by itself, as in "who am I", it must be lowercase; look at the third trigger: "do you know who i am". The other syntax error is because of the question mark: triggers contain no punctuation. Later in the tutorial you'll learn how to deal with punctuation in the user's messages by using substitutions.

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:

Comment Example
// This is the simple trigger again
+ hello bot    // What the human says
- Hello human! // How the bot responds
¤ Try Online

Comments are completely ignored by the RiveScript interpreter.

- Response

The minus symbol (-) tells the interpreter how to reply when the human matches the Trigger that came before it. In our example, it tells the interpreter to respond by saying "Hello human!" when the human says "hello bot".

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

Random Responses
+ hello bot
- Hello human!
- Hello!
- Hi there!
- Hey!
- Hi!
¤ Try Online

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

While having random replies can be useful, what if you want certain replies to be favored over others? You could just copy and paste the preferred replies several times so that it has a higher chance of being chosen, but it's easier to just assign some weight to them.

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:

Weighted Random Responses
+ hello bot
- Hello human!
- Hello!{weight=5}
- Hi there!
- Hey!{weight=5}
- Hi!{weight=10}
¤ Try Online

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
The effect is the same as though you copied and pasted each of the weighted responses that many times. If you did that you would end up with 22 responses, 5 of which saying "Hello!", 5 saying "Hey!", and 10 saying "Hi!". The {weight} tag just makes this simpler and easy to manage.

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