Quick Start

In this quick start guide you will create a JAICF project from an existing template and then we'll go briefly through it's sources.

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 from version Control from the menu. Paste this template's URL https://github.com/just-ai/jaicf-template and click Clone.

That is all! This simple project implements a voice application for Google Actions platform. On the next steps we have to create a Dialogflow agent and connect it with our dialogue scenario.

2. Run the project

To run our project you have only to click on green play button in Server.kt file.

This will start a local server on port 8080. We have now to make it public for the 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. Just copy it and go to the final steps.

3. Create a Dialogflow agent

Go to dialogflow.com, sign in and create a new agent. Here you have to open Fulfilment settings, enable fulfilment feature and paste your URL. Click Save then.

Then go to two existing intents and enable fulfilment for each in the bottom of page. Click Save for each intent.

4. Test it!

Great! You have created a new JAICF project and connected it with Dialogflow agent. Now it is time to test how it works.

Just click on Google Assistant link on right side bar and then click on Talk to my test app button. This launches a conversation between Google Assistant and your JAICF project.

Template project doesn't implement much interesting dialogue scenario thus it ends the session on every user's phrase that doesn't math to greeting intent.

A bit explanations

Now we are going to go through the project's source briefly to understand in general how it works.

Dependencies

Let's look on the build.gradle.kts file. Here a JAICF libraries from jcenter repository are defined in the dependencies section:

repositories {
    mavenCentral()
    jcenter()
}

dependencies {
    implementation(kotlin("stdlib-jdk8"))

    implementation("com.justai.jaicf:core:$jaicf")
    implementation("com.justai.jaicf:google-actions:$jaicf")
    implementation("com.justai.jaicf:mongo:$jaicf")

    implementation("io.ktor:ktor-server-netty:$ktor")
}

Scenario

Let's look on the MainScenario source file.

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

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.

Learn more about channels here.

Bot configuration

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 is a templateBot configuration that holds the MainScenario and configures desired activators - ActionsDialogflowActivator and CatchAllActivator.

Learn more about different activators here.

HTTP Server

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.

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

• cross-platform support
• managing a dialogue state
• automatic testing
• and much more

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