# QiChat - Syntax¶

### concept¶

Syntax

concept:(name) [word1 word2 "word3 word4"]



Where:

• word1 and word2 are isolated words,
• “word3 word4” is a phrase, i.e. a group of several words,
• name is the name of the static concept gathering all the items in an ordered list.

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?  ### dynamic¶ 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: • from QiChat using the ^addToConcept(~myConcept, myNewContent) or ^removeFromConcept(~myConcept, myContentToRemove), or • in your code by using the corresponding EditablePhraseSet. 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: • load items before running the Chat action, or • if it is necessary to load items while the robot is speaking, then do it via an ^execute command. 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"))


QiChatbot qiChatbot = ...;
EditablePhraseSet editablePhraseSet = qiChatbot.dynamicConcept("mp3");
List<Phrase> phrases = new ArrayList<>();



More

### description¶

Syntax

description: cook



Usage

Current focus description is in variable $Dialog/FocusDescription. If focus doesn’t have description, then variable is empty. ### topic¶ Syntax topic: ~name ()  Usage Defines the name to the topic. A topic must have one name and can have only one. Related functions ## Rules¶ ### User rule¶ 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 ### User subrule¶ 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. • If a User rule matches and if it has a scope, its subrules (u1:) are activated; the other User rule remain activated. • If one of the u1: subrule matches, then its own subrules (u2:) are activated, and the first-level rules (u1:) are deactivated. • At anytime, if another User rule matches, then the previous subrules are deactivated. Scope 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 ### Proposal¶ 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 ### pronunciation¶ 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  ### def:¶ 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 ## Delimiters¶ ### Choice: [ ]¶ Syntax u:([word1 word2 wordn]) answer u:(input) [word1 word2 wordn] u:([word1 word2 wordn]) [word1 word2 wordn] human  Where: • word1 to wordn are words that could substitute with each other. Warning Never write [{xxx}] the dialog engine will accept it but this rule will always match, whatever you write inside. Usage • In a Human input: creates one rule accepting variations. • In a Robot output: if the rule is triggered several times, the words will be used sequentially in order to create varying responses. 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 ### Phrase delimiter: ” “¶ Syntax u:([word1 "phrase 1"]) ["phrase 2" "phrase 3"]  Where: • word1 is a word that could substitute with phrase 1. • phrase 2 and phrase 3 are phrases used sequentially in order to create varying responses. 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  ### Optional part: { }¶ 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: • Not correct: u:([chocolate milk {bread}]) • Correct: u:([chocolate milk “{white} bread”]) 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 ## Special characters¶ ### Comments: #¶ Syntax # comment  Comment is defined by character #. All the characters following # in the same line will be ignored. ### Wildcard: *¶ 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 ### Forbidden word: !¶ 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!  ### Bookmark: %¶ 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 ### Input storing: _¶ 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

### Variable: $¶ 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:(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 ### Conditions: == > <> <¶ Syntax # condition on variable u:($variableName==value) answer

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. ### Robot events: e:eventName¶ 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: • any event providing information about the Dialog engine, • any QiChatVariable modification. 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/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
>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



### Concept call: ~¶

Syntax

u:(~conceptName) answer



Usage

A Concept can be used both in Human input or Robot output to replace a list of item previously declared.

• In Human input, the rule will match if anyone of the items of the list is recognized.
• In Robot output, one item of the list will be said. Each call of the rule will call sequentially another item of the list.

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 ## Forbidden characters¶ ### Forbidden characters in Human input¶ • Type only the words to be recognized. • Do not use any punctuation mark. • Do not use any special characters, for example: • instead of ‘$’, type: ‘dollar’
• instead of ‘.’, type: ‘dot’
• Apostrophe ( ‘ ) is allowed but not the typographic apostrophe ( ’ ).

Japanese only:

• speech recognition does not support Fullwidth numbers [０ １ ２ ３ ４ ５ ６ ７ ８ ９]. Use Halfwidth numbers [0 1 2 3 4 5 6 7 8 9] instead.

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?



• like all Special characters, $is a reserved word, type dollar instead. • warning: the character ‘.’ is a punctuation character, therefore, the robot will not read it: • Instead of ‘toto.png’, type: ‘toto dot png’ • Apostrophe ( ‘ ) is allowed but not the typographic apostrophe ( ’ ). 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?  ## Rule functions and properties¶ ### ^addToConcept¶ 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

### ^clearConcept¶

Syntax

u:(input) ^clearConcept(~conceptName)



Usage

Empties the dynamic concept with named conceptName.

Example

topic: ~introduction ()

dynamic:fridge
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

### ^concatenate¶

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



### ^empty¶

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)



### ^enable ^disable¶

Syntax

u:(input) answer ^disable(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



### ^enableThenGoto¶

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

### ^enableThenGotoInTopic¶

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

### ^endDiscuss¶

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.

### ^enumerate¶

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
I have beer red wine
I have white wine
I have beer red wine



Related functions

### ^exact¶

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



### ^execute¶

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.

### ^exist ^notExist¶

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. ### ^first¶ 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: • without any condition nor non-affected variable, • including affected variable(s), • including a condition tested as true. 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



For further details, see : Conditions: == > <> <.

### ^firstOptional¶

Syntax

u:(input) ^firstOptional [answer1 answer2]

# Inside a choice, requires quotes



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:(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 ### ^lessPriority¶ 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  ### ^nextProposal¶ 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 ### ^pick¶ 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 ### ^previousProposal¶ 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 ### ^private¶ 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  ### ^rand¶ 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: • an answer including a condition tested as true or • an answer including no condition at all. 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"]  ### ^releaseFocus¶ 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  ### ^removeFromConcept¶ 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

### ^repeat¶

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.

### ^sameProposal¶

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?
Ok I'll repeat. Do you want some coffee?
> yes
I'm bringing you a cup of coffee.



Related functions

### ^size¶

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 ### ^stayInScope¶ 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  ### ^topic¶ 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 ### ^topicRandom¶ 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 ### ^user_defined_function¶ 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



## Topic properties¶

### ^fallback¶

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.

### ^keepFocus¶

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

u:(e:Dialog/Fallback) can you answer my question ?  ^enableThenGoto(bookmark)



### ^noPick¶

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.

### ^noStay¶

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.

### ^postProcess¶

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.



### ^preProcess¶

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.



### ^preProcessReplace¶

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.



### ^resetOnFocus¶

Syntax

topic: ~introduction ^resetOnFocus ()



Usage

By default a proposal can be said only once.

^resetOnFocus reactivates all proposals of a Topic when:

• the topic gets the Focus and
• all his proposals has been previously deactivated.

## Transformation rules¶

### Skin: s:¶

Syntax

s:(Answer) Modifications
Modifications



Where:

• Answer is the Robot output we want to match to apply this skin
• Modifications the modifications ^addword or/and ^replace we want to apply to the answer

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:

• an integer: for instance “2” if you want to put the Expression in the second position
• “end” if you want the Expression to be added at the end of the sentence
• “start” if you want the Expression to be added at the beginning of the sentence
• 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



Execution

> hello
hey hello human I am your father
> how are you
hey I am fine and you



### ^replace¶

Syntax

s:(Answer) ^replace(Expression1, Expression2, Frequency)



Where:

• Answer is the Robot output to be matched
• Expression1 can be any string (word(s), concept…) you want to replace
• Expression2 can be any string (word(s), concept…) you want to put instead of Expression1
• Frequency is the probability of the skin to be applied (1:always, 0:never)

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



## Time & Date methods¶

### ^currentDate¶

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

### ^currentDateTime¶

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

### ^currentTime¶

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

### ^endOfWeek¶

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

### ^sayDate¶

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 ### ^sayTime¶ 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 Engine events¶

### Dialog/NotUnderstood¶

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¶

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



Execution

>where is bob
>bob is in the kitchen
ok, I'll remember
>where is bob
bob is in the kitchen



### Dialog/Fallback¶

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