Topics

---

Introduction — Triggers — Replies — Conversations — Topics — Plugins and Functions — Knowledge — Under the Hood

---

Topics

A topic is way to group triggers and replies together in some arbitrary, or logical way. There are no limit to how many topics you create. SuperScript will continue to try to find matches for your input outside of your current topic. All dialogue belongs to a topic and even if you do not select any topics, those triggers and replies will be stored in the random topic.

Creating a new topic

You can create new topics using the editor, or the following SuperScript syntax:

> topic:system:keep topic_name (keyword_1 keyword_2)

  + *
  - Hello!

< topic

Each topic has these properties:

• flags (optional): keep, system, nostay (see below)
• topic name (mandatory): unique, no spaces
• keywords (optional) help with the topic flow

Note: Unlike in RiveScript, in SuperScript topics cannot be nested!

Sorting gambits in topics

A topic can include any number of gambits, and the system will try to match them in the order they are written in the imported SuperScript file. You can sort the gambits in the editor automatically (the greediest trigger will be sorted last), or by drag & drop.

Weight

In SuperScript syntax, the default sorting can be overridden by using {weight=XX} in the input (note that this is different from Rivescript, where weight is used in replies):

+ * John {weight=80}
- Hello there

+ hello * {weight=90}
- Who are you?

In the above example, Hello John will be matched by the second rule, because of the weighting.

Changing to a new topic

To switch to a new topic, you can use {topic=topic_name} in the reply:

+ I like animals
- Me too! {topic=animals}

If you are in a custom plugin you can also change topics directly by accessing the user object method setTopic(...).

exports.somefunction = function(cb) {
  this.user.setTopic("newTopic")
  cb(null, "")
}

Topic changing only sets the recommended next topic on the next reply but does not guarantee a match. You could also get false positive matches out of context. When the user quits the conversation, the last topic he was in is saved, so next time the user logins, he starts in the same topic.

Topic hooks

Everytime the system tries to match an input, there are two special topics that run, one before your current topic, and one after. We call them pre and post hooks or topics. If you need some trigger to be tested on every pass either before or after the regular triggers, this is where you would put it. Pre and Post topics have a slightly different behavior, but function the same as normal topics. (for more details see Topic Flow below)

Topic flags

Topics can have a flag attached to them that modifies its behaviour: keep, system and nostay.

• keep is designed to disable to default behavior of exhausting triggers, if you want the bot to say things over and over again, and apply keep just after the topic definition.
• system topics do not appear in the normal topic flow and you must provide your own way to access them, usually the ^respond(topic_name) function works great for that. See Plugins and Functions
• nostay can be used to bounce from one topic, but return back to the previous topic right after. It might be a good way to break the flow up and allow the possibility to change the topic, but not do so forcefully.

Additional details & examples needed.

Topic flow

As noted earlier, the topic logic has improved to allow for easier scripting, and your bot should have access to more gambits. It is important that your topics have well defined keywords, this will help when trying to figure out what topic to check next.

Whenever we get an input from the user, the system will look for an answer in the following topics, in order. Keep in mind that system topics will never appear in the normal flow (unless they are the current topic):

1. pre topic
2. Current topic
3. Next best matched topic(s). Matching is done by using TF-IDF on the input and topic keywords—tech details here.
4. Any remaining non-system topics, including random
5. post topic

You can match more than once. Providing your match does not produce any output, the system will keep looking for matches. This is extra helpful when you have plugins or functions that try to do extra parsing on the message or make assumptions that may be false.

Note that the goal of SuperScript is to create human-like chatbots, and this is why the topic flow is not as deterministic as RiveScript or Hubot. The lack of keep and arbitrary feeling rules for picking or switching topics makes creating deterministic bots more difficult, but it is better for simulating how real people act (“Hey, I got bored and changed the topic to something else, maybe”).

---

Continue to Plugins and Functions