Syntax
concept:(name) [word1 word2 "word3 word4"]
Where:
Note: a static concept can contain choices, optional words and phrases, concepts (static and dynamic), functions (^rand, ^first), variables and conditions.
Usage
Defines a static list of items (words and/or phrases).
Warning
Phrase means a group of word, not a sentence, be aware that any punctuation character will be automatically removed.
Static concepts are global, in other words, they are usable in different Topics.
To use a concept in a rule, see: Concept call: ~.
Example
topic: ~introduction ()
concept:(greetings) ^rand[hi hello "hey there"]
concept:(wine) [red white] wine
concept:(alcohol) [beer ~wine]
u:(~greetings) ~greetings
u:(do you have _~alcohol) yes, I have $1
u:(I want to drink something) do you want ~alcohol?
Execution
> hey there
hello
> do you have white wine?
yes, I have white wine
> I want to drink something
do you want beer?
> I want to drink something
do you want red wine?
Syntax
dynamic:name
Note: a dynamic concept can only contain a list of words or phrases between a single choice [ ].
Usage
Declares a dynamic list of items (words and/or phrases).
Should be used in the very specific case when a content is not known before execution.
Note
Always prefer topics.
When a content is already known before execution, to make it vary during execution, think about enabling/disabling topics rather than using dynamics.
Conditions
Dynamic concept must be modified at runtime. You can do so:
To use a concept in a rule, see: Concept call: ~. Concepts are global, setConcept will affect the concept in all topics.
Warning
Be aware that adding too many items in a Dynamic concept will affect loading duration. For instance, loading a Dynamic concept containing thousands of sentences may take several minutes.
Moreover, for each item loaded, the robot has to stop then restart his listening activity. Therefore, too many items loaded in a row will necessarily degrade the quality of the user experience.
Good practice - Loading Dynamic concepts
To avoid unwanted blinks:
Example
topic: ~dynamic()
dynamic:mp3
u:({please} ["i want" play] _~mp3) let's play $1
val qiChatbot: QiChatbot = ...
editablePhraseSet: EditablePhraseSet = qiChatbot.dynamicConcept("mp3")
val phrases: MutableList<Phrase> = mutableListOf<Phrase>(Phrase("mika"), Phrase("queen"), Phrase("village people"), Phrase("boy george"))
editablePhraseSet.addPhrases(phrases)
QiChatbot qiChatbot = ...;
EditablePhraseSet editablePhraseSet = qiChatbot.dynamicConcept("mp3");
List<Phrase> phrases = new ArrayList<>();
phrases.add(new Phrase("mika"));
phrases.add(new Phrase("queen"));
phrases.add(new Phrase("village people"));
phrases.add(new Phrase("boy george"));
editablePhraseSet.addPhrases(phrases);
More
Syntax
description: cook
Usage
Current focus description is in variable $Dialog/FocusDescription. If focus doesn’t have description, then variable is empty.
Syntax
u:(Input) Answer
u:(Input)
Answer
Where:
Indentation and blank lines are ignored.
Usage
Makes the robot say or do the Answer when he hears the Input.
Effect
If the Human input matches, then the topic that contains the rule takes the focus.
For further details, see: Focus.
Conditions
The topic containing the user rules must be activated to answer.
Example
topic: ~introduction ()
u:(hello) hello human
u:(how are you) I feel tired, my batteries are low
Execution
> hello
hello human
> how are you
I feel tired, my batteries are low
Related functions
Syntax
u:(input1) answer
u1:(input2) answer
u1:(input3) answer
u2:(input4) answer
u3:(input5) answer
u2:(input6) answer
proposal: sentence
u1:(input7) answer
u1:(input8) answer
Where u1:, u2: and u3: are user subrules.
Usage
Allows creating several conversational contexts, making some rules activated if and only if a main User rule or Proposal has previously matched.
Activation / deactivation
At first, the User rules and Proposal are activated while subrules are deactivated.
The subrules of a rule are called the scope of the rule.
Example
topic: ~introduction ()
u:(talk about animals) do you have a cat or a dog?
u1:(dog) is it a big dog?
u2:(yes) make sure he has enough space to run
u2:(no) it is so cute
u1:(cat) do you live in the countryside?
u2:(yes) does your cat goes outside?
u3:(yes) does he hunt mouses?
u2:(no) i hope your flat is big enough
u1:(none) neither do I
u:(talk about sport) what a good idea
proposal: Do you want to talk about sport?
u1:(yes) Cool
u1:(no) OK
Execution
> talk about animals
do you have a cat or a dog?
> I have a cat
do you live in the countryside?
> no
I hope your flat is big enough
> Now I want to talk about sport
what a good idea
Related functions
Syntax
proposal: sentence
Where:
Usage
While rules are triggered by a Human input, to be said, a Proposal needs to be triggered with one of the topic progression functions:
Activation/deactivation
When a proposal is said, then it cannot be said again except if the proposal is re-activated by ^enableThenGoto.
Conditions
The Topic containing the user rules must be active.
Example
topic: ~introduction ()
proposal: take a cup and fill it with milk
proposal: add 3 strawberries
proposal: add some vanilla ice cream
proposal: close the cup with the lid and shake it
proposal: you did it! you can enjoy your milkshake
u:(I want a milkshake)
ok, let's do it.
follow my instruction and say next when you are ready for the next step.
u:(next) ^nextProposal
Execution
> I want a milkshake
ok, let's do it.
follow my instruction and say next when you are ready for the next step.
>next
take a cup and fill it with milk
>next
add 3 strawberries
>next
add some vanilla ice cream
>next
close the cup with the lid and shake it
>next
you did it! you can enjoy your milkshake
>next
(no answer)
Related functions
Syntax
pronunciation:(word) wordPronunciation
Usage
Changes the default speech recognition way to pronounce a word. For example “I” should be pronounced “capitalize i”.
Note: Following words pronunciation are automatically managed by dialog engine: “I” in English and “Ã ” in French.
topic: ~play()
pronunciation:(I) [i]
u:(I want to play) let's play
Syntax
def:name($parameter1, $parameter2, ..) robot output
Note:
Every parameter is local to the function in which it has been defined. Outside of this function every occurrence of $parameter1, $parameter2, .. will be replaced by the value stored in memory.
Usage
Defines a function which can be used in other qiChat rules as any function.
Related functions
Syntax
u:([word1 word2 wordn]) answer
u:(input) [word1 word2 wordn]
u:([word1 word2 wordn]) [word1 word2 wordn] human
Where:
Warning
Never write [{xxx}] the dialog engine will accept it but this rule will always match, whatever you write inside.
Usage
Warning
Single quotes ‘ ‘ do not concatenate words together. If you need to concatenate words into a phrase, you must use double quotes ” “.
Example:
u:(hello [“my mate” “my friend”]) is interpreted correctly, but
u:(hello [‘my mate’ ‘my friend’]) is interpreted as u:(hello [my mate friend])
Example
topic: ~introduction ()
u:([hi hello]) [hello hi] human
The Human input can be ‘hello’ or ‘hi’. The Robot output can be ‘hello human’ or ‘hi human’. By default answers are in a sequential order.
Execution
> hello
hello human
> hello
hi human
> hi
hello human
Related functions
Syntax
u:([word1 "phrase 1"]) ["phrase 2" "phrase 3"]
Where:
Usage
Allows you to place a phrase instead of a single word in a choice [] or an optional part {}.
Example
topic: ~introduction ()
u:(["hello how are you" "hello are you OK"]) ["I am fine" "I am OK"]
Execution
> hello are you OK
I am fine
> hello how are you
I am OK
Syntax
u:(beginning of the sentence {optionalWord} end of the sentence) answer
u:(input) beginning of the sentence {optionalWord} end of the sentence
u:(beginning of the sentence {"optional phrase"} end of the sentence) answer
u:(input) beginning of the sentence {"optional phrase"} end of the sentence
Where:
Usage
Optional word or phrase, at the beginning, the middle or the end of a sentence.
Conditions
Inside a Choice: [ ], optional word for Human input can only be used inside a phrase:
Example 1
topic: ~introduction()
u:(hello {buddy} how are you) hello I am fine
Execution of Example 1
>hello how are you
hello I am fine
>hello buddy how are you
hello I am fine
Example 2
topic: ~introduction()
u:(hey) hello {human buddy}
Execution of Example 2
>hey
hello human
>hey
hello buddy
>hey
hello
In this example, each element inside of the Optional part: { } is picked with a probability of 1/3 (corresponds to a choice: [human buddy ^empty]).
Related rules
Syntax
# comment
Comment is defined by character #. All the characters following # in the same line will be ignored.
Syntax
u:(sentence * sentence) answer
Usage
Matches any word or phrase.
Use wildcards sparingly
Too many wildcards can degrade performance of the automatic speech recognition.
Example
topic: ~introduction ()
u:(my name is *) nice to meet you
u:(I like to * a lot) it sounds cool
Execution
> my name is David
nice to meet you
> I like to dance a lot
it sounds cool
> I like to play tennis a lot
it sounds cool
Related functions
Syntax
u:(sentence !forbiddenWord) answer
Usage
Allows you to define a forbidden word in a Human input.
Example
topic: ~introduction ()
u:(tell me a story) OK, a new one?
u:(!don't tell me a new one) great, I'll tell you a new story!
u:(don't tell me a new one) Ok, so I'll tell you the story of Peter Pan.
Execution
> tell me a story
OK, a new one?
> tell me a new one
great, I'll tell you a new story!
Syntax
proposal: %bookmark sentence
u:(input) %bookmark answer
Usage
Allows you to identify one or several proposal(s) or rule(s) by a Bookmark. Bookmarks can be activated or deactivated. If a Bookmark is deactivated, then the sentence is false and won’t be said.
Example
Related functions
Syntax
u:(sentence _[word1 word2]) answer $1
u:(sentence _~concept) answer $1
u:(sentence _*) answer $1
Where:
_[word1 word2] is the choice of words the robot will be able to catch and reuse.
$1 is the first caught word.
If there are several _, $2 is the second caught word, $3 is the third, etc. There is no limitation in variable number.
_~conceptName allows catching any word included in a concept. For further details, see: Concept call: ~.
_* allows catching any word said using the remote speech recognition.
Warning
_* is not available for all robots and all languages, it requires a specific remote speech recognition license.
Note: giving a choice of words to recognize eases the speech recognition.
Usage
Allows catching one or several words in the Human input and reuse it within the Robot output directly following.
Tips: if you need to reuse the value elsewhere in the dialog, store it in a variable.
u:(my name is _*) nice to meet you $1 $name=$1
Example
topic: ~introduction ()
u:(my name is _*) nice to meet you $1
u:(I like _[chocolate cheese]) do you want to eat $1 now?
Execution
> my name is David
nice to meet you David
> I like cheese
do you want to eat cheese now?
> I like chocolate
do you want to eat chocolate now?
Related functions
Syntax
# Affect a variable
u:(input) answer $variableName=value
# Say a defined variable in a robot answer
u:(input) answer $variableName
# Listen to a defined variable in an input - Warning: requires remote speech recognition.
u:(input $variableName) answer $variableName
Where:
variableName is the name of the variable.
See also the usage of variable in: Conditions: == > <> <.
Usage
Variables are used to store text data so that it can be manipulated in QiChat. They are global to their QiChatbot, i.e. they can be used in several topics, and all topics will share the same value. They contain strings and don’t need to be declared, they can be directly affected and used in rules.
When a variable is set or updated, an event is raised. See: Robot events: e:eventName to react to an event.
A defined variable can be:
said in a Robot output,
tested in a condition (see: Conditions: == > <> <), or
listened in a Human input, but only if the remote speech recognition is available.
Note
Depending on the availability of remote speech recognition, variables may not match when used in input.
Say there is a variable $name containing “Alice”, and the following QiChat command:
topic: ~introduction ()
u:(my name is $name) hello $name
If there is no remote then the robot will not be able to understand “my name is Alice”.
However, it is still possible to trigger a rule by testing a condition on a variable, and / or use the event triggered by a variable change as an input.
Example
topic: ~introduction ()
u:(I want some _[chocolate cheese]) OK $askedFood=$1
u:(e:askedFood) You asked for a new food
u:(what did I ask) ^first["you asked $askedFood" "I don't know"]
Execution
> what did I ask
I don't know
> I want some chocolate
OK
You asked for a new food
> what did I ask
you asked chocolate
Related functions
Syntax
# condition on variable
u:($variableName==value) answer
# answer if variable>value
u:(input) answer $variableName>value
# answer if variable<value
u:(input) answer $variableName<value
# answer if variable different from value
u:(input) answer $variableName<>value
# condition on variable in human input, using an event
u:(e:Dialog/SpeakFailure $variableName==value) answer
# condition on variable in human input
u:("input $variableName==value") answer
# condition on variable in answer
u:(input) ["answer $variableName==value" "another answer"]
Usage
Placed in a Human input or in a Robot output, a condition will, if false, prevent the [corresponding part of a] rule from being instantiated.
Example
u:(my name is _[robert maximilian *]) hello ^first["$1==robert bob" "$1==maximilian max" "my friend"]
Execution
my name is robert
> hello bob
my name is sandy
> hello my friend
my name is maximilian
> hello max
A condition based on an empty variable will always be considered false.
Comparisons are made based on the conversion to float of the given variables. If any of the variables in the comparison is not a numeric value, the comparison is considered false.
Example
u:(I have _[2 3 4 5 nine] cakes) oh, that's nice $cakes=$1
u:(if 3 people eat 1 slice, would I have any left)
^first[
"$cakes>3 yes"
"$cakes<3 you don't have that many cakes to begin with"
"$cakes==3 no"
"I don't know precisely how many cakes you have"
]
Execution
if 3 people eat 1 slice, would I have any left
> I don't know precisely how many cakes you have
I have 3 cakes
>oh, that's nice
if 3 people eat 1 slice, would I have any left
> no
I have 4 cakes
>oh, that's nice
if 3 people eat 1 slice, would I have any left
> yes
I have nine cakes
>oh, that's nice
if 3 people eat 1 slice, would I have any left
>I don't know precisely how many cakes you have
I have 2 cakes
>oh, that's nice
if 3 people eat 1 slice, would I have any left
> you don't have that many cakes to begin with
See also: ^first.
Syntax
u:(e:event) answer
# will answer whenever the event "event" is raised
u:([e:event sentence]) answer
# will answer whenever the event "event" is raised or the sentence is said.
u:("e:event sentence") answer
# will answer whenever the event "event" is raised and then the sentence is said
# (the event must be raised before saying the sentence)
Note: only one event can be matched at a time. If several events are raised at the same time, other events with the same name are rejected until dialog engine answered. Other events with different names have two seconds to be matched by dialog engine or they will be rejected.
Note: compatible events can be QiChatVariable updates (from QiChat or from code) or a Dialog Engine events.
Usage
Catches an event.
Allows to catch:
Note
Robot output cannot occur at high frequency, both data and event are merged.
Example
topic: ~introduction ()
u:(where is bob) bob is in the $bobLocation
u:(bob is in the _[bathroom kitchen]) ok, I'll remember $bobLocation=$1
u:(e:Dialog/NotUnderstood) I don't understand
u:(e:Dialog/SpeakFailure) I can't answer this
u:(e:Dialog/Fallback) I matched in a fallback, and now I came back
topic: ~fallbackTopic ^fallback ()
u:(I like apples) that's not really interesting.
Execution
> bla bla
I don't understand
>where is bob
I can't answer this
>bob is in the kitchen
ok, I'll remember
>where is bob
bob is in the kitchen
>I like apples
that's not really interesting. I matched in a fallback, and now I came back
Syntax
u:(~conceptName) answer
u:(input) answer ~conceptName
Usage
A Concept can be used both in Human input or Robot output to replace a list of item previously declared.
Conditions
the Concept must be previously defined.
To define a concept, see: concept and dynamic.
Example
topic: ~introduction ()
concept:(want) [want need desire like]
concept:(alcohol) [beer vodka "red wine"]
concept:(child-drink) ["orange juice" milk]
concept:(drink) [~alcohol ~child-drink]
u: (what do you do) I can help people with drinks
u:(I ~want to drink) what you ~want to drink?
u1:(* _~drink) do you want me to search $1 for you?
Execution
> what do you do
I can help people with drinks
> I need to drink
what do you want to drink?
> I want red wine
do you want me to search red wine for you?
Related functions
Japanese only:
Example
topic: ~introduction ()
u:(have you a dollar for me) No, sorry, I have no pocket!
u:(I'm rich) good for you. Are you happy?
Example
topic: ~introduction ()
u:(have you a dollar for me) No, sorry, I have no pocket!
u:(I'm rich) good for you. Are you happy?
Syntax
u:(input) ^addToConcept(~conceptName, myWord)
Usage
Adds the expression myWord to the dynamic concept named conceptName.
Example
topic: ~introduction ()
concept:(drink) [coke sprite water "iced tea"]
dynamic:fridge
u:(put some _~drink in the fridge) ok ^addToConcept(~fridge, $1)
u:(what's in the fridge) the fridge contains ^enumerate(~fridge)
Execution
> put some coke in the fridge
ok
> put some water in the fridge
ok
> what's in the fridge
the fridge contains coke water
Related functions
Syntax
u:(input) ^clear(variableName)
Usage
Clears a variable. A cleared variables cannot be said. A sentence with cleared variable cannot be said. A condition with cleared variable is always false.
Example
topic: ~introduction ()
u:(my name is _*) nice to meet you $name=$1
u:(what is my name) ^first["your name is $name" "I don't know"]
u1:(no) OK ^clear(name)
Execution
> my name is David
nice to meet you
> what is my name
your name is David
> no
OK
> what is my name
I don't know
Related functions
Syntax
u:(input) ^clearConcept(~conceptName)
Usage
Empties the dynamic concept with named conceptName.
Example
topic: ~introduction ()
dynamic:fridge
u:(put drinks in the fridge) ok ^addToConcept(~fridge, coke) ^addToConcept(~fridge, beer)
u:(what's in the fridge) The fridge contains ^size(~fridge) drinks
u:(empty the fridge) ok, I empty the fridge ^clearConcept(~fridge)
Execution
> put drinks in the fridge
ok
> what's in the fridge
The fridge contains 2 drinks
> empty the fridge
ok, I empty the fridge
> what's in the fridge
The fridge contains 0 drinks
Related functions
Syntax
u:(input) ^concatenate(car1, var2, .., varN)
Usage
Concatenates all the variables and outputs the result.
Example
topic: ~concatenate()
concept:(letter)[A N P U L]
u:(my name is 4 letters) Oh, can you spell it for me?
u1:(_~letter _~letter _~letter _~letter) Oh, so your name is ^concatenate($1, $2, $3, $4)")
Execution
> my name is 4 letters
Oh, can you spell it for me?
> A N N A
Oh, so your name is ANNA
Syntax
u:(input) ^empty
Usage
Used when the robot should not answer.
Tip: can be used inside a Choice: [ ], e.g. the robot does not answer immediately to a Human input but only the second time.
Warning
Do not use empty string “” for this purpose: empty strings are skipped.
Example 1
topic: ~example1()
u:(hello) [^empty "Hi human"]
#Warning:
#u:(hello) ["" "Hi human"] will not work the same way, as "" are skipped.
Execution of Example 1
>hello
(no robot output)
>hello
Hi human
Example 2
topic: ~example2()
u:(hello) ^goto(bookmark)
u:(test) ^empty
u:(^empty) %bookmark "Hi human"
Execution of Example 2
>hello
Hi human
>test
(no robot output)
Syntax
u:(input) answer ^disable(bookmark)
u:(input) answer ^enable(bookmark)
Usage
^disable function deactivates a Bookmark, ^enable function reactivates a Bookmark.
If a Robot output contains a deactivated Bookmark, this Robot output cannot be triggered.
Example
topic: ~introduction()
proposal: %greeting1 hello
proposal: nice to meet you
u:(hello) hello ^disable(greeting1)
u:(say something) ^nextProposal
Execution
> Hello
Hello
> say something
nice to meet you
Syntax
proposal: %bookmark Answer
u:(input) ^enableThenGoto(bookmark)
Usage
The ^enableThenGoto function allows to jump, inside the same topic, to a deactivated Proposal. To jump to a deactivated Proposal from another topic, use ^enableThenGotoInTopic.
Example
topic: ~introduction ()
proposal: %love I love you
u:(do you love me) yes, ^enableThenGoto(love)
u:(are you sure) sure, ^enableThenGoto(love)
Execution
I love you
> do you love me
yes, I love you
> are you sure
sure, I love you
Related functions
Syntax
proposal: %bookmark Answer
u:(input) ^enableThenGotoInTopic(bookmark,topic)
Usage
The ^enableThenGotoInTopic function allows you to jump to a deactivated Proposal from another topic and reactivate it.
Related functions
Syntax
u:(input) output ^endDiscuss(end reason)
Usage
This function will stop the current QiChatbot with the string “end reason” as a result.
Warning
^endDiscuss stops the current qiChatbot, but not the Chat action.
To make the robot fully stop listening, see: Ending a chat.
Syntax
u:(input) ^enumerate(~conceptName)
u:(input) ^enumerate(~conceptName, 2)
Usage
Enumerates all the elements of a static or dynamic concept.
A second parameter can be used to limit the number of enumerated elements. Calling several time the function will move forward in the concept.
Example
topic: ~introduction ()
concept:(alcohols) [beer "[red white] wine"]
u:(what are your drinks) I have ^enumerate(~alcohols)
u:(enumerate your drinks) I have ^enumerate(~alcohols, 2)
Execution
> what are your drinks
I have beer red wine white wine
> enumerate your drinks
I have beer red wine
> enumerate your drinks
I have white wine
> enumerate your drinks
I have beer red wine
Related functions
Syntax
u:(Input ^exact) Answer
Effect
The Dialog Engine allows more words in input than in rule itself. For example, the rule “Hello robot” will match the input “hello”. If you want to match exactly the pattern of the rule, use ^exact.
Example
topic: ~test ()
u:(hi ^exact) hello
u:(e:Dialog/NotUnderstood) What did you say?
Execution
> hi robot
What did you say?
> hi
hello
Syntax
topic: ~execute()
u: (raise your _[right left] arm) I raise my $parameter1 arm ^execute(myExecutor, $parameter1, parameter2) then I resume talking
Usage
The ^execute allows to execute a piece of code during the conversation. When reaching ^execute the associated QiChatExecutor will call its runWith method with the passed parameters. After the code execution the conversation will be resumed where it was stopped.
Warning
Be aware that the robot will not speak during the execution, so, in order to avoid a long pause in the middle of a speech, make sure you do not place ^execute in the middle of a sentence.
Note
The first parameter is mandatory and corresponds to the key that must be given when adding the associated BaseQiChatExecutor to the QiChatbot.
The other parameters are optional and correspond to the BaseQiChatExecutor runWith parameters.
Syntax
topic: ~exist()
u:(hello) ["^exist(42) the variable exist" "^notExist(42) the variable doesn't exist $42=1"]
Usage
A sentence that contains ^exist won’t be said if the variable parameter does not exist or is an empty string.
Syntax
u:(input) ^first [answer1 answer2]
# Inside a choice, requires quotes
u:(input) [answer1 "^first [answer2 answer3]"]
Usage
When added before a Choice: [ ] in the Robot output part, instead of using each answer in turn, the interpreter always use the first valid Robot output.
A valid Robot output is an answer:
Using a non-affected variable in a robot output will make the rule invalid, i.e. the rule will not be said at all.
To avoid this situation, use the function ^first before a choice [ ].
This function tries to say the first valid output. If the first element of the choice is invalid because it contains a non-affected variable or a condition that evaluates to false, it will try the second element, and so on. If none of the elements is valid, the ^first will be deemed invalid.
Example
topic: ~introduction ()
u:(my name is David) nice to meet you David $name=David
u:(my name is Paul) nice to meet you Paul $name=Paul
u:(what is my name) ^first["your name is $name" "I don't know"]
Execution
> what is my name
I don't know
> my name is David
nice to meet you David
> what is my name
your name is David
For further details, see : Conditions: == > <> <.
Syntax
u:(input) ^firstOptional [answer1 answer2]
# Inside a choice, requires quotes
u:(input) [answer1 "^firstOptional [answer2 answer3]"]
Usage
This function tries to say the first valid output. If the first element of the choice is invalid because it contains a non-affected variable or a condition that evaluates to false, it will try the second element, and so on. If none of the elements is valid, the ^firstOptional will be evaluated as nothing.
Example
topic: ~introduction ()
u:(my name is David) nice to meet you David $name=David
u:(my name is Paul) nice to meet you Paul $name=Paul
u:(my name is a secret) I won't tell anyone ^clear(name)
u:(hello) good morning ^firstOptional["$name"]
Execution
> my name is David
nice to meet you David
> hello
good morning David
> my name is a secret
I won't tell anyone
> hello
good morning
For further details, see : Conditions: == > <> <.
Syntax
u:(input1) %bookmark Answer
u:(input2) ^goto(bookmark)
Usage
The ^goto function allows you to:
Example
topic: ~introduction ()
u:(hello how are you) hello ^goto(how)
u:(how you are) %how I'm fine
Execution
> how are you
I'm fine
> hello how are you
hello I'm fine
Related functions
Syntax
u:(input1) %bookmark1 output1
proposal: %bookmark2 output2
u:(input) ^output ^gotoAnyFromList(bookmark1, bookmark2)
Usage
The ^gotoAnyFromList allows to jump randomly to an instance of a bookmark from this topic randomly picked from the given list.
Related functions
Syntax
u:(input) ^gotoRandom(bookmark)
proposal: %bookmark answer1
proposal: %bookmark answer2
Usage
The ^gotoRandom function is identical to ^goto except if the Bookmark is used in several rules, it will chose one randomly.
Example
topic: ~introduction ()
u:(hello) ^gotoRandom(hi)
proposal: %hi hello
proposal: %hi welcome
proposal: %hi hey
Execution
> hello
hey
> hello
hello
> hello
welcome
Related functions
Syntax
^gotoInTopic(bookmark,topic)
Usage
Allows going in a specific location in a topic, defined by a Bookmark.
Example
topic: ~topic1()
proposal: %test test
topic: ~topic2()
u:(test) ^gotoInTopic(test,topic1)
Related functions
Syntax
u:(input) ^isInConcept(~conceptName, myWord)
Usage
Checks whether myWord is in the dynamic concept named conceptName.
Example
topic: ~introduction ()
concept:(drink) [coke sprite water "iced tea"]
dynamic:fridge
u:(put some _~drink in the fridge) ok ^addToConcept(~fridge, $1)
u:(Do you have some cold _~drink) ^first["^isInConcept(~fridge, $1) yes I have" "no I don't"]
Execution
> Do you have some cold iced tea?
no I don't
> put some iced tea in the fridge
ok
> Do you have some cold iced tea?
yes I have
Related functions
Syntax
u:(Input ^lessPriority) Answer
Effect
Reduces the rule priority. In case of matching conflict with another rule, the rule with ^lessPriority won’t be chosen.
Example
topic: ~test ()
u:(hello ^lessPriority) good morning
u:(hello) hi
Execution
> hello
hi
Syntax
u:(input) answer ^nextProposal
Usage
The function ^nextProposal says the first activated proposal in the Topic which has the Focus.
Example
topic: ~introduction ()
u:(hi) hello ^nextProposal
proposal: how are you?
u1:(I'm fine) cool!
u1:(I'm tired) oh, you should take a nap
proposal: again!
Execution
> hi
hello how are you?
> I'm tired
oh, you should take a nap
> hi
hello again!
Related functions
Syntax
u:(input) ^pick(myTopicName)
Usage
After using ^pick function on a topic, the Dialog Engine will be able to pick the proposals from the given topic (with ^topicRandom for example) even if it had the ^noPick property.
Example
topic: ~notPickable ^noPick()
proposal: I like pickles
topic: ~test()
u:(say something) ^topicRandom
u:(e:Dialog/NothingToSay) I have nothing to say. Do you want me to say something?
u1:(yes) ok ^pick(notPickable) ^topicRandom
u1:(no) that's a shame.topic: ~notPickable ^noPick()
Execution
> say something
I have nothing to say. Do you want me to say something?
> yes
ok
I like pickles
Related functions
Syntax
u:(input) answer ^previousProposal
Usage
The function ^previousProposal repeats the Proposal said previously to the last in the same Topic.
Example
topic: ~introduction ()
u:(hi) hello ^nextProposal
proposal: how are you?
u1:(I'm fine) cool!
u1:(I'm tired) oh ^nextProposal
proposal: do you want some tea?
u1:(yes) I'm bringing you a cup of tea.
u1:(no) okay, ^nextProposal
proposal: what about some coffee?
u1:(yes) I'm bringing you a cup of coffee.
u1:(no) okay, maybe you should just take a nap.
u:(what did you say before) ^previousProposal
Execution
> hi
hello how are you?
> I'm tired
do you want some tea?
> no
OK, what about coffee?
> what did you say before
do you want some tea?
Related functions
Syntax
u:^private(Input) Answer
Effect
Apply a private status to a rule. A private user rule is only active when its corresponding topic has the Focus.
Example
topic: ~music ()
u:(I want to talk about music) OK!
u:^private(what are we talking about) we are talking about music
Execution
> I want to talk about music
OK!
> what are we talking about
we are talking about music
Syntax
u:(input) ^rand[answer1 answer2]
Usage
Can be added before a choice [] in the Robot output.
Instead of using each answer sequentially, the interpreter will choose randomly a valid Robot output.
A valid Robot output is:
Rand function in a choice needs to be inside quote.
For further details, see: Conditions: == > <> <.
Example
u:(hello) ^rand[hello hi "what's up" "hey there"]
Syntax
u:(input) output ^releaseFocus
Usage
Leave the current topic.
Example
topic: ~topicName()
Proposal: how are you ?
u1:(well) great ^releaseFocus
u1:(bad) great ! ^releaseFocus
Syntax
u:(input) ^removeFromConcept(~conceptName, contentValue)
Usage
Removes the content contentValue from the dynamic concept with named conceptName.
Example
topic: ~introduction ()
concept:(drink) [coke sprite water "iced tea"]
dynamic:fridge
u:(fill the fridge) ok ^addToConcept(~fridge, coke) ^addToConcept(~fridge, beer)
u:(what's in the fridge) the fridge contains ^enumerate(~fridge)
u:(remove the _~drink from the fridge) ok ^removeFromConcept(~fridge, $1)
Execution
> fill in the fridge
ok
> what's in the fridge
The fridge contains coke beer
> remove the coke from the fridge
ok
> what's in the fridge
The fridge contains beer
Related functions
Syntax
u:(^repeat[word1 word2 word3]) answer
Note: Repeat allows you to use words or sentences from one to ten times.
Warning
This function is tricky. Avoid to start your first interaction with repeat. Avoid to use Wildcard * in repeat.
Usage
Allows a free combination of listed words.
The Human input is recognized if one or several word(s) among the list are said, regardless of the order.
Syntax
u:(input) answer ^sameProposal
Usage
The function ^sameProposal repeats the last proposal said in the same topic.
Best practices
When using ^sameProposal, always make the robot say something like ‘Ok I’ll repeat’, ‘No problem,’ so that the user knows what to expect. It also makes the repetition clearer.
Example
topic: ~introduction ()
u:(hi) hello ^nextProposal
proposal: how are you?
u1:(I'm fine) cool!
u1:(I'm tired) oh ^nextProposal
proposal: do you want some coffee?
u1:(yes) I'm bringing you a cup of coffee.
u1:(no) okay, maybe you should just take a nap.
u1:(can you repeat please) Ok I'll repeat. ^sameProposal
Execution
> hi
hello how are you?
> I'm tired
do you want some coffee?
> can you repeat please
Ok I'll repeat. Do you want some coffee?
> yes
I'm bringing you a cup of coffee.
Related functions
Syntax
u:(input) ^size(~conceptName)
Usage
Returns the number of elements in a static of dynamic concept.
Example
topic: ~introduction ()
dynamic:cocktails
concept:(alcohols) [beer "[red white] wine" ~cocktails]
u:(how many drinks do you have) I have ^size(~alcohols)
u:(do you have any cocktails) $size="^size(~cocktails)" ["$size==0 no" "yes I have $size cocktails"]
Execution
> how many drinks do you have
I have 3
> do you have any cocktails
no
Related functions
Syntax
u:(input) answer
u1:(input1) answer ^stayInScope
u1:(input2) answer
Usage
Used in a rule or subrule to stay in the current scope when the corresponding rule has matched.
Example
u:(let's talk about animals) do you have a cat or a dog?
u1:(I {also} have a dog) dogs are funny ^stayInScope
u1:(I {also} have a cat) I once met a cat ^stayInScope
Execution
> let's talk about animals
do you have a cat or a dog?
> I have a dog
dogs are funny
> I also have a cat
I once met a cat
Syntax
u:(input) ^topic(topicName)
Usage
The ^topic function allows you change the current topic to the topic with the given name, and say a proposal from this topic if there is a valid one.
Example
topic: ~cats()
u:(talk about an animal) cats are felines
u:(let's talk about something else) ok ^topic(dogs)
topic: ~dogs()
u:(talk about an animal) dogs are canines
u:(let's talk about something else) ok ^topic(cats)
Execution
> talk about an animal
cats are felines
> let's talk about something else
ok
> talk about an animal
dogs are canines
Related functions
Syntax
proposal: %bookmark Answer
u:(input) ^topicRandom
Usage
The ^topicRandom function allows you to jump to an activated Proposal among activated topics. If no proposal are available, function has no effect and event Dialog/NothingToSay is raised.
Related functions
Syntax
^user_defined_function($parameter1, $parameter2, ..)
Usage
Allows you to use a function previously defined with def:.
Example
topic: ~test()
def:greets($age) ^first["$age > 18 Mister" "kid"]
u:(I am _* years old) Hello ^greets($1)
Execution
> I am 20 years old
Hello Mister
> I am 10 years old
Hello kid
Syntax
topic: ~introduction ^fallback ()
Usage
Give the lowest priority to the rules contained in this topic.
Its rules will be taken in consideration after the rules of:
1 - the main section of the Topic having the focus,
2 - the main section of all Topics - ^fallback excepted.
See also: Priority among Topics.
Syntax
topic: ~topicName ^keepFocus()
Usage
Forces to keep focus in the topic. If an input from another topic matches, then the answer of the other topic is said but the focus stays in keepFocus topic and an internal event e:Dialog/Fallback is raised.
Example
topic: ~topicName ^keepFocus()
Proposal: %bookmark how are you ?
u1:(well) great ^releaseFocus
u1:(bad) great ! ^releaseFocus
u:(e:Dialog/Fallback) can you answer my question ? ^enableThenGoto(bookmark)
Syntax
topic: ~introduction ^noPick ()
Usage
Prevents the topic from getting randomly the Focus.
The Topic can still get the focus when a rule matches, but the Dialog engine cannot decide by itself to give the focus.
Syntax
topic: ~introduction ^noStay ()
Usage
Prevents the topic from keeping the Focus.
If a rule matches in the topic, the Robot output is executed, but the Focus stays on the previous topic.
Syntax
topic: ~introduction ^postProcess ()
Usage
Allows a double topic match if another rule has already matched. The ^postProcess answer is said after the other topic answer. The ^postProcess rules cannot be matched on their own. The ^postProcess rule triggers can only be events (other content will never be matched).
Example
topic: ~topic1()
u:(hello) hello.
topic: ~topic2 ^postProcess()
u:(e:FrontTactilTouched) you touched me.
Execution
> hello (when variable FrontTactilTouched value changes)
hello. you touched me.
Syntax
topic: ~introduction ^preProcess ()
Usage
Allows a double topic match if another rule has already matched. The ^preProcess answer is said before the other topic answer. The ^preProcess rules cannot be matched on their own. The ^preProcess rule triggers can only be events (other content will never be matched).
Example
topic: ~topic1()
u:(hello) hello.
topic: ~topic2 ^preProcess()
u:(e:FrontTactilTouched) you touched me.
Execution
> hello (when variable FrontTactilTouched value changes)
you touched me. hello.
Syntax
topic: ~introduction ^preProcessReplace ()
Usage
Allows to replace a rule by another, ONLY when the 2 rules are matched. The ^preProcessReplace rules cannot be matched on their own. The ^preProcessReplace rule triggers can only be events (other content will never be matched).
Example
topic: ~topic1()
u:(hello) hello.
topic: ~topic2 ^preProcessReplace()
u:(e:FrontTactilTouched) you touched me.
Execution
> hello
hello.
> hello (when variable FrontTactilTouched value changes)
you touched me.
Syntax
s:(Answer) Modifications
s:(Answer)
Modifications
Where:
Usage
When a Robot output matches a skin the robot says the Answer after Modifications are applied.
Syntax
s:(Answer) ^addword(Expression, Position, Frequency)
Where:
Answer is the Robot output to be matched
Expression can be any string (word(s), concept…)
Position is the position where you want to add the expression in the sentence.
This parameter can be:
Frequency represents the probability of the skin to be applied (1:always apply, 0:never apply)
Usage
Add an Expression in each Robot output matching the skin.
Conditions
The rule must be active.
Example
topic: ~introduction ()
u:(hello) hello human
u:(how are you) I am fine
s:(hello human) ^addword(I am your father, end, 1)
s:(*) ^addword(hey, start, 1)
Execution
> hello
hey hello human I am your father
> how are you
hey I am fine and you
Syntax
s:(Answer) ^replace(Expression1, Expression2, Frequency)
Where:
Usage
Replaces Expression1 with Expression2 in each Robot output matching the skin.
Conditions
The rule must be active.
Example
topic: ~introduction ()
u:(hello) hello human
u:(what do you like to do) I like to speak with you human
u:(do you want to play) yes human we can play together
s:({*} human {*}) ^replace(human, Michael, 1)
s:({*} speak {*}) ^replace(speak, play, 1)
If you are not familiar with {*} check: Wildcard: * to under Optional part: { }.
Execution
> hello
hello Michael
> what do you like to do
I like to play with you Michael
> do you want to play
yes Michael we can play together
Syntax
u:(input) ^currentDate
Usage
Returns the current date at format:
YYYY-MM-DD
If ^sayDate is user defined, the robot will say the date according to your own formatting.
Example
topic: ~date()
u:(what is the current date) ^currentDate
Related functions
Syntax
u:(input) ^currentDateTime
Usage
Returns the current date and time at format:
YYYY-MM-DD hh:mm
If ^sayDateTime is user defined, the robot will say the date according to your own formatting.
Example
topic: ~date()
u:(what is the current date time) ^currentDateTime
Related functions
Syntax
u:(input) ^currentTime
Usage
Returns the current time at format:
hh:mm
If ^sayTime is user defined, the robot will say the date according to your own formatting.
Example
topic: ~date()
u:(what is the current time) ^currentTime
Related functions
Syntax
u:(input) ^endOfWeek
Usage
Returns the date of the next sunday. If ^sayDate is user defined, the robot will say the date according to your own formatting.
Example
topic: ~date()
u:(what is next sunday date) ^endOfWeek
Related functions
Syntax
def: sayDate($year, $month, $day) myRule
Usage
When defined, strings in the format YYYY-MM-DD (ie dates) will be processed by this function, with YYYY being $year, MM being $month and DD being the day
Exemple
topic: ~date ()
u:(when is your birthday) 2017-12-25
u:(when is max's birthday) 2017-11-25
def: sayDate($year, $month, $day) ^first["$month==12 $day==25 on christmas" "some unimportant day"]
Execution
> when is your birthday
on christmas
> when is max's birthday
some uninmportant day
Related functions
Syntax
def: sayDateTime($year, $month, $day, $hours, $minutes) myRule
Usage
When defined, strings in the format YYYY-MM-DD (ie dates with time) will be processed by this function, with YYYY being $year, MM being $month, DD being the day, hh being the hour and mm the minutes.
Exemple
topic: ~date ()
u:(when did you see paul) 2017-12-31 23:59
u:(when was peter born) 2017-11-25 14:30
u:(when did you see maria) 2017-12-31 11:59
def: sayDateTime($year, $month, $day, $hour, $minutes) ^first["$month==12 $day==31 $hour==23 minutes==59 on new year's eve" "who cares"]
Execution
> when did you see paul
on new year's eve
> when did you see maria
who cares
> when was peter born
who cares
Related functions
Syntax
def: sayTime($hour, $minutes) myRule
Usage
When defined, strings in the format hh:mm (ie times) will be processed by this function. with hh being $hour and mm being $minutes
Example
topic: ~date ()
u:(when are you supposed to meet) 12:48
u:(when did bob arrive) 07:30
def: sayTime($hour, $minute) ^first["$hour==12 during lunch" "some time during the day"]
Execution
> when are you supposed to meet
during lunch
> when did bob arrive
some time during the day
Related functions
Dialog/NotUnderstood is raised every time a human speaks and QiChatbot has no answer for the human input.
Warning
Dialog/NotUnderstood is an internal event, which means it is not possible to create, in your code, a variable based on it.
Example
u:(e:Dialog/NotUnderstood) I don't understand
Execution
> bla bla
I don't understand
Dialog/SpeakFailure is raised every time a human speaks and QiChatbot cannot fully solve the answer it should use.
Warning
Dialog/SpeakFailure is an internal event, which means it is not possible to create, in your code, a variable based on it.
Example
topic: ~introduction ()
u:(where is bob) bob is in the $bobLocation
u:(bob is in the _[bathroom kitchen]) ok, I'll remember $bobLocation=$1
u:(e:Dialog/SpeakFailure) I can't answer this
Execution
>where is bob
I can't answer this
>bob is in the kitchen
ok, I'll remember
>where is bob
bob is in the kitchen
Dialog/Fallback is raised every time a human speaks and QiChatbot uses a Topic defined with ^fallback to answer.
Warning
Dialog/Fallback is an internal event, which means it is not possible to create, in your code, a variable based on it.
Example
topic: ~introduction ()
u:(e:Dialog/Fallback) I matched in a fallback, and now I came back
topic: ~fallbackTopic ^fallback ()
u:(I like apples) that's not really interesting.
Execution
>I like apples
that's not really interesting. I matched in a fallback, and now I came back