QiChat - Syntax

Header keywords

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).

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.

Example

topic: ~dynamic()

dynamic:mp3
u:({please} ["i want" play] _~mp3) let's play $1

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

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.

https://developer.softbankrobotics.com/sites/default/files/repository/60_rst_pepper/public/source/_build/html/_images/qichat_scope.png

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

topic: ~introduction ()

proposal: %weather what is the weather like today?
u:(tell me a story) %story ok, I'll tell you the story of the three bears

Related functions

More


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:(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


Conditions: == > <> <

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.


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/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


Concept call: ~

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.

  • 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 [0 1 2 3 4 5 6 7 8 9]. 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?

Forbidden characters in Robot output

  • 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


^clear

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


^clearConcept

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


^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)
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


^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
> 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


^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
your name is David

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


^firstOptional

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: == > <> <.


^goto

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


^gotoAnyFromList

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


^gotoRandom

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


^gotoInTopic

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


^isInConcept

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


^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?
> can you repeat please
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
u1:(bad) 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
s:(Answer)
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.


^addword

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

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


^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


^sayDateTime

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

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