-
Notifications
You must be signed in to change notification settings - Fork 39
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.
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.
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.
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.
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.
Now we are going to go through the project's source briefly to understand in general how it works.
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.
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
.
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.
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 examples on the Github repository.