A BaseChatbotReaction
is an abstract class that is the parent class of all custom ChatbotReaction
implementations.
This class must be inherited to implement the effective reactions needed when your own Chatbot has to execute
its replies or autonomous reactions.
See also API doc: BaseChatbotReaction.
Create a class that inherits BaseChatbotReaction
and implements the required methods, runWith
and stop
.
runWith
is aimed at executing the reaction. It is only run if the chat engine chooses this reaction after it has
been replied by your chatbot implementation.stop
may be called by the chat engine during the execution of runWith
if this answer has to
be stopped for any reason (lost focus, interruption by an AutonomousReaction
whose priority is higher, etc.).Instances of this custom class will then be passed as first parameter when constructing either StandardReplyReaction
or StandardAutonomousReaction
objects.
For further details, see: StandardReplyReaction and StandardAutonomousReaction.
The only obligation of the BaseChatbotReaction
heirs constructors is to provide their parent constructor with the
current QiContext
, which can be obtained as parameter of these constructors.
An additional parameter of the constructor may typically be the text to be uttered as an answer.
class MyChatbotReaction(context: QiContext, answer: String) : BaseChatbotReaction(context) {
}
public class MyChatbotReaction extends BaseChatbotReaction {
private String answer;
protected MyChatbotReaction(QiContext context, String answer) {
super(context);
this.answer = answer;
}
}
However, this pattern is not mandatory: for example the heard phrase may be passed instead if your custom
BaseChatbotReaction
is itself in charge of choosing an answer according to the heard phrase.
This method gathers all the actions that make up the effective reaction that will be executed upon chat engine decision.
The typical implementation is the execution of a Say
action, but alternative or additional actions may be used.
For example, an Animation
may be executed along with a Say
, or alone for a mute answer.
Important
Any Say
action that is run in this method must be created by using the SpeechEngine
provided as
parameter. Actions created via SayBuilder.with(qiContext)
cannot be executed here. Use SayBuilder.with(speechEngine) instead.
In order to make your BaseChatbotReaction
interruptible by the chat engine, the method should:
Future
instances that hold the asynchronous executions of the actions,
in dedicated fields of your custom BaseChatbotReaction
.These futures will then be accessible to the stop
method (see below).
Despite the fact that actions are run asynchronously, the runWith
method must wait its running actions before leaving.
Important
The runWith
method should not return before all of its actions are terminated. The execution
must wait for the futures to be done.
See stop.
override fun runWith(speechEngine: SpeechEngine) {
// Build the Say action
val say: Say = SayBuilder.with(speechEngine)
.withText(answer)
.build()
// Run asynchronously the action and keep a reference to the future in a field
fSay = say.async().run()
// Do not leave the method before the actions are done
try {
fSay?.get()
} catch (e: ExecutionException) {
Log.e(TAG, "Error during Say", e)
} catch (e: CancellationException) {
Log.i(TAG, "Interruption during Say")
}
}
@Override
public void runWith(SpeechEngine speechEngine) {
// Build the Say action
Say say = SayBuilder.with(speechEngine)
.withText(answer)
.build();
// Run asynchronously the action and keep a reference to the future in a field
fSay = say.async().run();
// Do not leave the method before the actions are done
try {
fSay.get();
} catch (ExecutionException e) {
Log.e(TAG, "Error during Say", e);
} catch (CancellationException e) {
Log.i(TAG, "Interruption during Say");
}
}
This is the ChatbotReaction
’s duty to cleanly cancel its actions upon request by the chat engine. The stop
method
is in charge of stopping these actions.
As stated earlier, it is important to keep references on the Future
objects that hold the actions being executed,
in order to make them available here.
The implementation of this method will mainly request the cancellation of these futures.
override fun stop() {
fSay?.cancel(true)
}
@Override
public void stop() {
if (fSay != null) {
fSay.cancel(true);
}
}
A StandardReplyReaction
is the standard implementation of ReplyReaction
. It defines the reaction of a chatbot
when the chat has heard something and it asks its chatbots to return a reply.
The StandardReplyReaction
is basically aimed at aggregating both a BaseChatbotReaction
(the effective answer
to be implemented) and the priority level of this reaction.
A StandardReplyReaction
must be returned by any heir class of BaseChatbot
via its replyTo
method.
It is constructed by providing it with a BaseChatbotReaction
instance along with a ReplyPriority
.
BaseChatbotReaction
parameter, in fact a heir of this abstract class,
contains the effective behavior of the reply (such as a Say
or an Animation
, or a combination of any actions).ReplyPriority
is an enum value that qualifies the type of the reply as either NORMAL
or FALLBACK
.
Fallback replies have a lower priority than a normal reply.return StandardReplyReaction(
MyChatbotReaction(qiContext, "Hi"),
ReplyPriority.NORMAL)
return new StandardReplyReaction(
new MyChatbotReaction(getQiContext(), "Hi"),
ReplyPriority.NORMAL);
See also API doc: StandardReplyReaction.
A StandardAutonomousReaction
is the standard implementation of AutonomousReaction
.
As opposed to the ReplyReaction
, the AutonomousReaction
is not a reply
that is requested as a reaction to an input but a “reaction” that is spontaneously
emitted by the chatbot upon its willingness, whenever it wants.
When needed, a StandardAutonomousReaction
instance must be created by providing it with a BaseChatbotReaction
instance
along with an AutonomousReactionImportance
and an AutonomousReactionValidity
.
BaseChatbotReaction
parameter, in fact a heir of this abstract class, contains the effective behavior of the autonomous
reaction (such as a Say
or an Animation
, or a combination of any actions).AutonomousReactionImportance
is an enum value that qualifies the importance of the reply as either HIGH
or LOW
.AutonomousReactionValidity
is an enum value that qualifies the time validity of the reply as either
IMMEDIATE
or DELAYABLE
.A delayable autonomous reaction can be enqueued if it is chosen by the chat whereas the immediate autonomous reaction will be discarded if it cannot be run immediately.
The autonomous reaction will be taken into account by the chat engine, by setting it on the chatbot instance.
// Create an BaseChatbotReaction heir instance
val myAutonomousChatbotReaction: MyAutonomousChatbotReaction = MyAutonomousChatbotReaction(qiContext)
// Create the AutonomousReaction
val autonomousReaction: StandardAutonomousReaction = StandardAutonomousReaction(
myAutonomousChatbotReaction,
AutonomousReactionImportance.LOW,
AutonomousReactionValidity.DELAYABLE)
// Assign the AutonomousReaction
myChatbot.setAutonomousReaction(autonomousReaction)
// Create an BaseChatbotReaction heir instance
MyAutonomousChatbotReaction myAutonomousChatbotReaction = new MyAutonomousChatbotReaction(getQiContext());
// Create the AutonomousReaction
StandardAutonomousReaction autonomousReaction = new StandardAutonomousReaction(
myAutonomousChatbotReaction,
AutonomousReactionImportance.LOW,
AutonomousReactionValidity.DELAYABLE);
// Assign the AutonomousReaction
myChatbot.setAutonomousReaction(autonomousReaction);
See also API doc: StandardAutonomousReaction.