Response List

Overview

A Response List is Bot Libre's text file format for defining a bot's responses. A response list is a list of question/response pairs. Each phrase is separated by a new line, and each question/response list is separated by an empty line. You can also tag responses with meta data such as keywords to influence when the response is used. Response lists are the recommended way to train a bot. The bot will automatically find the best matching response for any question, the questions do not need to be exact matches, only sufficiently similar, or include a keyword.

Response Tags

Tag	Description
question:	Defines the question. This is not required, as the first line after a blank line is assumed to be a new question.
pattern:	Defines a question as a pattern. Patterns allow the wildcard * and other wild cards to be used.
response:	Defines a response. This is not required, as any lines after the question as assumed to be responses.
template:	Defines a response template. This lets you embed Self code inside {} brackets for dynamic responses.
sentiment:	You can associate sentiment (good/bad) with the phrase.
condition:	Optionally you can give a condition in self code that must evaluate to true for the response to be use.
think:	Optionally you can give a 'think' code in self that is evaluated when the response is used.
command:	Optionally you can give a JSON command (Self code) that is evaluated and returned to the client to support games and virtual assistance.
topic:	Optionally you can give a topic to categorize the response under.
require topic:	If the topic is required, the response will only be used when the topic is active.
exclusive topic:	If the topic is exclusive, only response that share the topic will be used while the topic is active.
label:	Optionally you can give a label to reuse the response as.
keywords:	Optionally you can give keywords from the question that will influence a response match.
required:	Optionally you can give required words from the question that will be required for a response match.
emotions:	You can associate an emotion with the response.
actions:	You can associate an action with the response.
poses:	You can associate a pose with the response.
on repeat:	Optionally you can give a response to used if the current response has already been used in this conversation.
no repeat:	Require that the response or phrase only be used once.
previous:	Optionally you can give a previous response to give a response a context.
require previous:	Require that the response only be used if the previous response matches one of the previous responses.
confidence:	Confidence can be used if a response is not certain. The matching response with the highest confidence will be used.

question:

The response question can be a phrase that will be automatically matched with similar questions, or can be a Pattern. Patterns are matched literally in the order of the words in the pattern, and can have wildcard characters such as * and can also include Regular Expressions. Normally it is best to use a phrase, and let the bot decide if a question should match, you can also add keywords and required words to improve when a question is matched. To enter a pattern use the pattern: tag.

what is your name

question: what is your name

pattern: What is *

response:

The response can be a phrase, can contain HTML or rich content including images, video, and buttons, or a response can be a Template. A template is a response that can include some Self code. Any code inside {} in a template will be executed, and the result printed into the response. To enter a template use the template: tag and enter Self code inside {} brackets.

My name is Julie.

My name is <b≷Julie</b≷.

response: My name is Julie.

template: My name is {#self.name}.

template: The date is {Date.date()}.

keywords:

Keywords are important words in the question that should influence when the response is used.

// Keywords are used to allow this response to be used for any questions on hockey or spinach.
question: do you like hockey
response: Hockey is my favorite sport.
keywords: hockey

question: what do you love
response: I love hockey!
keywords: love luv like adore

question: do you like field hockey
response: I only play ice hockey.
keywords: "field hockey"

question: i love spinach
response: Spinach is is my favorite food.
keywords: spinach

A keyword will be used by the bot to select the best response. Keywords let some words count for more than other words. In the example, the bot knows two responses, how will it respond to the phrase "I love hockey"? Without the keywords the bot would probably match this question with "I love spinach", but since hockey is a keyword, it will instead match it with "Do you like hockey?".

If the response has no defined required words, then the keywords will also be required for the response match. So "I love hockey" would not be matched with "I love spinach." because it is missing the keyword.

If you keywords has many similar words. You can list them all as keywords to match any of the words. You could also define these words a synonyms, which may be a better option.

You can also use compound words are keywords. A compound keyword must have all the words in the order to be used. For a compound keyword just wrap the words in "quotes".

Be careful using too many keywords. If every word is a keyword, then their value is diminished. Never make common words like "the", "a", "he", "what" keywords, if you require one of these words for a match use a required word instead.

You can also review all of your bot's keywords by searching for 'words' and restrict to 'keywords'. This lets you remove a word from being a keyword if you added it by mistake.

required:

A required word is a word that is required to be in the question for a specific response.

// This example requires the words 'like' and 'hockey'.
question: do you like hockey
response: Yes, I like hockey.
required: like hockey

// This example requires the compound word 'ice hockey'.
question: do you like ice hockey
response: Yes, I like ice hockey.
required: "ice hockey"

// This example requires one of the words 'like' or 'love', and 'hockey'.
question: do you like ice hockey
response: Yes, I like ice hockey.
required: (like love) hockey

// This example requires a pattern.
question: are you okay
response: Yes, I am okay.
required: Pattern("^ are you (ok okay)")

A required word can be used to ensure the bot does not choose a response if the required word is missing from the question. For example the question "Do you play hockey?" would normally be matched to this response, but because it is missing the required word "like", it will not be considered as a match.

All of the required words must be contained in the question in order for the response to be used. Required words also supports lists, compound words, and patterns. To require one of a set of words a list can be used using brackets i.e. (like love). To require a compound word quotes are used i.e. "hello world". To require a pattern enter the pattern i.e. Pattern("what is *").

A previous responses is the bot's preceding response. Previous responses can be used to give a response a context.

// This example uses previous to give different answers to 'yes' depending on the context.
question: yes
response: Great, wanna go out sometime?
require previous: Are you single?

question: yes
response: I am please to hear that.
require previous: Are you happy?

The question "Yes" has multiple responses. The bot can use the previous response to choose the best response. You can also invalidate a previous response to ensure the bot does not use a response if the previous response was preceding.

A previous response can either be 'required' or optional. If required, the response will never be used unless one of the previous response matches. If optional (default) the response is given precedence if the previous response matches, but can still be used if the previous does not match.

topic:

A topic is the general topic category for the response. For example a response on a hockey related question would belong to the "hockey" topic. You can use topics to categories your responses and give the bot additional context. If the bot has multiple responses to a question, it will use the one that matches the current topic.

Topics can be either optional or required. The response topic is optional by default, it you click on 'Require Topic', then the response will only be used if that topic is active in the conversation. If optional the topic will be set as active for the conversation, until a new topic is set.

Topics can also be defined as exclusive. An exclusive topic defines an isolated conversational space. For a normal topic that is not exclusive the bot can still use responses that do not have the same topic, but responses with the active topic will be given precedence over responses without a topic. For exclusive topics only response that have the same topic as the active topic will be used. No other responses will be used (other than possibly the default response if there is no topic default).

Topics can also be set on greetings to start the conversation with a topic. Topics can be set on default responses to provide a different response when that topic is active.

// Categorizes the product response.
question: what are your products
response: Our products include ACME CRM and ACME ERP.
topic: products

// Use an exclusive topic to define a joke conversational dialog.
question: joke
response: Knock knock.
exclusive topic: joke

question who is there
response: Boo.
require topic: joke

question: boo who
response: Don't cry. lol
require topic: joke
think: conversation.topic = null;

default: Say 'Who is there?'
require topic: joke

default: Say 'Boo who?'
require topic: joke
previous: boo

label:

A response can be given an intent label to let you reuse the same response in other questions. You can also use labels in a response's previous.

// Use a label to reuse the common products response.
question: products
response: Our products include ACME CRM and ACME ERP.
label: #products

question: what are your products
response: #products

question: what software do you sell
response: #products

question: are they good
response: Our products are the best in the world.
previous: #products

on repeat:

If the user asks the same question, or similar questions multiple times, you may want your bot to give a different response the second time. On repeat lets you set one or many responses to use the second time that response is triggered in the same conversation. You can also set 'No Repeat' to never repeat the response in the same conversation.

// Offer to escalate the issue if the user repeatedly asks for help.
question: help
response: How can I help you?
on repeat: What is the issue that you are having?
on repeat: Would you like me to have a support staff contact you?

question: goodbye
response: Before you go, would you like to take a survey?
no repeat:

question: goodbye
response: Goodbye.

condition:

Conditions let you enter Self code that must evaluate to true for the response to be used. This is an advanced properties as it requires you understand Self (a dialect of JavaScript), but can be used to do very powerful things.

// Response to goodbye differently based on the time of day.
question: goodbye
response: Goodnight.
condition: Date.get(#hour, Date.time()) > 18

question: goodbye
response: Goodbye.

think:

Think let you enter Self code that is executed when the response is used. This is an advanced properties as it requires you understand Self (a dialect of JavaScript), but can be used to do very powerful things.

// Track the user's name.
pattern: my name is *
template: Pleased to meet you {star}.
think: speaker.name = star;

question: what is my name
template: Your name is {speaker.name}.

question: can we change the subject
response: Sure, what would you like to talk about?
think: conversation.topic = null;

confidence:

You can enter multiple responses for the same question. The bot will use the response that it is the most confident in for the current conversational context. By default a response is given a confidence level of 90%, but you can customize the value. Note that in a group discussion such as when the bot is added to a chatroom, or on Twitter, the bot will only use responses that have >=90% confidence.

sentiment:

You can associate a user question or phrase, or individual words with sentiment (good vs bad). Sentiment can be used to track how the user is feeling about the current conversation. The sentiment statistic is tracked by your bot daily and can be graphed from its Analytics page.

question: thank you
response: You are most welcome.
keywords: thank
sentiment: good

question: you suck
response: Sorry, I am doing my best. Would you like me have someone contact you via email?
keywords: suck
sentiment: bad

word: suck
sentiment: bad

word: great
sentiment: great

Next and Conversation Flows

Next questions in a response can be used to handle follow-up questions and conversation flows. To start a conversation flow, indent the next follow-up question to the response. You can use tabs or 4 spaces for indents. You can also indent multiple levels to define a conversation tree.

A respones next question defines an isolated conversation space. The bot will only choose its next response from the provided responses. To define a default response use the default: tag. If the bot cannot match the user's question with a next question, it will search the responses parent, otherwise use the bot's default response.

Next is similar to previous, but unlike previous is isolated to the response. In the context of a next response, the bot will never use any of its responses outside the context of the next response. This makes is easy to define isolated and nested conversations.

question: help
response: Do you want help with <button>web</button> or <button>mobile</button>
keywords: help

	question: web
	response: Is you issue with <button>HTML</button> or <button>JavaScript</button>?

		question: html
		response: See https://www.w3schools.com/html

		question: javascript
		response: See https://www.w3schools.com/js

	question: mobile
	response: Are you using <button>Android</button> or <button>iOS</button>?

		question: android
		response: See https://www.android.com

		question: ios
		response: See https://developer.apple.com/ios

	question: quit
	response: Okay. Let me know if you need further help.

	default: Please specify <button>web</button> or <button>mobile</button>, or type <button>quit</button> if you do not need help.

Greetings

A greeting is the bot's first response in a new conversation. Greetings can have most of the same tags as responses. To define a greeting the greeting: tag is used.

greeting: Welcome to my website. I am Julie, how may I be of service?

Default Responses

If the bot does not find any good matching question to a user's input, it uses its default response. Default responses can have most of the same tags as responses. To define a default response the default: tag is used.

default: Sorry, I do not understand.
			
default: Sorry, I do not understand. Please email [email protected] for more information.
topic: Sales

Phrases

Phrases can be defined to associate sentiment, emotions, action, or poses to a phrase.

thanks for the help
sentiment: good

you are not helping me
sentiment: bad

Words

Word can be defined to associate sentiment, emotions, and synonyms. A word can also be a keyword, a topic, or an exclusive topic.

word: good
sentiment: good
synonyms: great wonderful cool amazing 

word: bad
sentiment: bad
synonyms: sucks terrible horrible

word: aiml
keyword: true
topic: true

Word Tags

Tag	Description
word:	Define a word.
sentiment:	Optionally you can associate a sentiment with the word.
emotions:	Optionally you can associate an emotion with the word.
keyword:	Define the word to be a keyword.
synonyms:	Optionally you can give a synonym to the word, so that similar words in a question to trigger the same response.
topic:	Define the word to be a topic.
exclusive topic:	Define the word to be an exclusive topic.