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 topic_name (keyword_1, keyword_2) {system, keep}

  + *
  - 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

Keywords are useful when you have two topics with the same triggers but different replies. So if the input I like tacos matches against replies in two different topics, the topic that has tacos as a key word will get preference.

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

Note: As of v1.0.0, topics cannot have the character ~ in their name, as this gets confusing when mixed with wordnet lookups.

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.

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 someFunction(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 they were in is saved, so next time the user logins, they start in the same topic.

Topic hooks

Every time 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, including keeping their replies (see keep flag in Topic Flags), but otherwise 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. Note that pre and post Topic Hooks automatically use this behaviour.
• 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. random topic if it hasn't previously been searched
5. Any remaining non-system topics
6. 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