Quick Start

To create a conversational application using JAICF you have to make these simple steps:

1. Have a Kotlin or Java project created
2. Include JAICF dependencies
3. Create scenario(s) of the dialogue
4. Connect it to the desired NLU engine and channels

In this quick start guide you will follow through all these steps to learn how to create a new conversational project using JAICF.

The source code of this guide is available on Github

1. Create a new project

To create a new project you have to have some appropriate IDE installed. We recommend to use IntelliJ IDEA due it's native support of Kotlin language.

Create a new project using File -> New -> Project -> Gradle from the menu. Then uncheck Java and check Kotlin DSL build script and Kotlin/JVM. Click Next then, name your project somehow and click Finish.

That is all! Your new project is ready. Now you have to add JAICF dependencies in your build.gradle.kts file.

2. Include JAICF dependencies

JAICF is a multi-modular framework. The only required module is core, all others are optional and add features to your project like NLU engine connectivity, channels support and others.

Add a jCenter repository to your build.gradle.kts file and the latest version of JAICF Core:

repositories {
    mavenCentral()
    jcenter()
}
dependencies {
    implementation(kotlin("stdlib-jdk8"))
    implementation("com.justai.jaicf:core:0.1.0")
}

Please check for the latest version of JAICF on the main page of Github repository.

In this guide we also use Google Actions to handle requests from Google Assistant. That is why you need to add one more dependency here:

implementation("com.justai.jaicf:google-actions:0.1.0")

3. Create dialogue scenario

Each JAICF driven project contains a set of dialogue scenarios that implement a conversational logic of your voice assistant or chat bot. Scenarios are simple Kotlin objects or classes and utilises a JAICF DSL to describe a dialogue in a declarative manner. Here is a very simple example:

object MainScenario: Scenario() {

    init {
        state("main") {
            activators {
                intent(DialogflowIntent.WELCOME)
            }

            action {
                reactions.say("Hi there!")
            }
        }

        state("fallback", noContext = true) {
            activators {
                catchAll()
            }

            action {
                reactions.say("I have nothing to say yet...")
                reactions.actions?.run {
                    say("Bye bye!")
                    endConversation()
                }
            }
        }
    }
}

A bit explanations here

JAICF scenario contains a set of dialogue states that can be nested in each other. Thus a context-aware dialogue with a hierarchy of states could be described via JAICF DSL. Every state could be activated by different activators like Intent that is recognised by NLU engine from the user's raw query.

Here is a MainScenario object that contains two root states named main and fallback. The main state can be activated by WELCOME intent of Dialogflow NLU engine. The second state named fallback is activated each time the user speaks something that is not handled by any other activators of any state. That is why it is named catchAll() activator.

Once the user speaks something that is recognised as a WELCOME intent (like "hi", "hello there" end etc.), JAICF activates a corresponding state main and executes it's action block. The same regarding the fallback state.

This scenario responds with simple "Hi there!" string once the main state is activated and "I have nothing to say yet..." on fallback.

You can see how the fallback state's action reacts when the request is going from Google Actions channel.

reactions.actions?.run {
    say("Bye bye!")
    endConversation()
}

Here is a Kotlin extensions power activated! When the user says something that is not handled by other states (catchAll), your scenario responds with the same "I have nothing to say yet..." but adds one more reply - "Bye bye!" and ends a conversation. endConversation() is a channel-related method of Google Actions channel library that switches off the Google Assistant microphone and exists from your Action.

Here you can see how it is easy to create conversational scenarios that can work simultaneously via different channels, but has logic forks for some of them.

4. Start a scenario

Obviously every scenario has to be ran to handle users' requests. To do that you have to instantiate a new BotEngine that holds your scenario and connects to the desired NLU engine.

val templateBot = BotEngine(
    model = MainScenario.model,
    activators = arrayOf(
        ActionsDialogflowActivator,
        CatchAllActivator
    )
)

Here we create a templateBot configuration that holds our MainScenario and configures desired activators - ActionsDialogflowActivator and CatchAllActivator.

To run this bot we have to start an HTTP server once Google Actions requires us to provide a webhook endpoint. JAICF already provides a ready to use Ktor extension that helps to use Ktor HTTP server with ease.

fun main() {
    embeddedServer(Netty, 8080) {
        routing {
            httpBotRouting(
                "/" to ActionsFulfillment.dialogflow(templateBot)
            )
        }
    }.start(wait = true)
}

Here we start Netty HTTP server on port 8080 and provide routing that proxies all requests to our bot.

Append one more dependency to your buidl.gradle.kts to be able to use Ktor Netty server:

implementation("io.ktor:ktor-server-netty:1.3.1")

Make it public

All we have to do now is to make this URL public for entire Internet. The easiest way to do this is to install ngrok and start ngrok http 8080 in the terminal. This generates a temporal public URL that can be used to configure a Fulfilment URL in the Dialogflow console.

Then you can start to to test your Google Assistant's action. Just enable fulfilment for every intent you wish to be handled by your scenario.

Where to go next

In this quick start guide you've learned how to create a new JAICF project and simple dialogue scenario, as well as how to start a webhook server for Google Actions channel and start to test your dialogue via Dialogflow console.

Of course JAICF enables you to create much more powerful and flexible things like

• multi-channel support
• jumping through states
• automatic testing
• and other things

To dive into the JAICF, we recommend to go next through the Introduction section and check for some examples on the Github repository.