BaseChatbotReaction¶

Implementing constructors¶

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.

Implementing runWith¶

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.

In order to make your BaseChatbotReaction interruptible by the chat engine, the method should:

• execute the actions asynchronously,
• store the references of the 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.

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");
    }
}

Implementing stop¶

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);
    }
}

How to use it¶

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.

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

How to use it¶

When needed, a StandardAutonomousReaction instance must be created by providing it with a BaseChatbotReaction instance along with an AutonomousReactionImportance and an AutonomousReactionValidity.

• The 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).
• The AutonomousReactionImportance is an enum value that qualifies the importance of the reply as either HIGH or LOW.
• The 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.