Amazon Alexa channel

Allows to create custom voice skills for Amazon Alexa.

Built on top of Alexa Skills Kit SDK for Java.

Usage example

Here is an example that shows how to use this channel in practice.

How to use

1. Include Alexa dependency to your build.gradle

implementation("com.just-ai.jaicf:alexa:$jaicfVersion")

Replace $jaicfVersion with the latest version

2. Use Alexa `request`, `activator` and `reactions` in your scenarios’ actions

state("launch") {

    activators {
        event(AlexaEvent.LAUNCH)
    }

    action {
        // Amazon SDK HandlerInput
        val input = request.alexa?.handlerInput
        val envelope = input?.requestEnvelope
    
        // Alexa named entities slots extracted from the user's query
        val slots = activator.alexaIntent?.slots
    
        // Use Alexa-specific response builders
        reactions.alexa?.endSession("See you later. Bye bye!")
        reactions.alexa?.playAudio("https://address.com/audio.mp3")
        reactions.alexa?.sendProgressiveResponse("Just a moment please...")
        
        // Or use standard response builders
        reactions.say("How are you?")
    }
}

Learn more about Amazon SDK HandlerInput and AlexaReactions.

Native response builder

You can also build a response directly via reactions.alexa?.response?.builder native builder. See details below.

3. Configure Alexa Activator

Alexa recognises user intents. That is why it is not possible to use third-party NLU engine. To make this channel work, you have to add AlexaActivator to the activators array of your agent’s configuration:

val helloWorldBot = BotEngine(
    scenario = MainScenario,
    activators = arrayOf(
        AlexaActivator
    )
)

4. Create and run Alexa webhook

Using JAICP

For local development:

fun main() {
    JaicpPollingConnector(
        botApi = helloWorldBot,
        accessToken = "your JAICF project token",
        channels = listOf(
            AlexaChannel
        )
    ).runBlocking()
}

For cloud production:

fun main() {
    JaicpServer(
        botApi = helloWorldBot,
        accessToken = "your JAICF project token",
        channels = listOf(
            AlexaChannel
        )
    ).start(wait = true)
}

Using Ktor

fun main() {
    embeddedServer(Netty, 8000) {
        routing {
            httpBotRouting("/" to AlexaChannel(helloWorldBot))
        }
    }.start(wait = true)
}

Using Spring Boot

@WebServlet("/")
class AlexaController: HttpBotChannelServlet(
    AlexaChannel(helloWorldBot)
)

Using AWS Lambda

class AWSLambda: AlexaLambdaSkill(helloWorldBot)

5. Configure Alexa Custom Skill

Create and sign-in to your Developer account on Alexa Developer Console.

Using external hosting

Create new custom skill and setup a HTTPS Endpoint on the Build tab using your public URL of the webhook.
Select “My development endpoint is a sub-domain of a domain that has a wildcard certificate from a certificate authority” in the drop-down list.

You can obtain a public URL of your webhook using ngrok for example. In the case of using JAICP just create new Alexa channel and use its webhook URL.

Using AWS Lambda

Create new AWS Lambda with Java 11 runtime and add Alexa Skills Kit trigger.
Build your JAICF project using shadowJar as described here and upload the resulting JAR file to your lambda.
Define the full name of your handler in Runtime settings, for example com.just-ai.jaicf.examples.gameclock.channel.AWSLambda::handleRequest

6. Provide custom intents

Alexa implements its own NLU engine that recognises a user’s requests and extracts named entities from their phrases. You have to provide at least one custom intent to the intents list on the left side bar of Alexa Developer Console.

7. Start testing

To start talking with your Alexa custom voice skill just click on Save Model and then Test tab. Here you have to enable Development mode to start testing your skill via test console or physical Amazon Echo device.

Just start test using command like “Start [your skill name]”.

Alexa intents and events

Alexa provides a built-in intents and events that can be used in your JAICF scenarios.

Please refer to the AlexaIntent and AlexaEvent.

object MainScenario : Scenario() {
    init {

        state("launch") {
            activators {
                event(AlexaEvent.LAUNCH)
            }

            action {
                reactions.say("Hi gamers! ${breakMs(300)}" +
                            "Game clock keeps track of the time for each player during the board game session." +
                            "$break500ms Are you ready to start a game?")
            }
        }

        state("cancel") {
            activators {
                intent(AlexaIntent.CANCEL)
            }

            action {
                reactions.alexa?.endSession("Okay $break200ms See you latter then! Bye bye!")
            }
        }
    }
}

Composing responses

You can use both standard and native response builders to compose responses.

action {
    reactions.say("This is a standard way to compose a response.")

    // Or use native builder
    reactions.alexa?.response?.run {
        // Response with card
        builder.withSimpleCard("Card title", "Card text")
        builder.withStandardCard("Card title", "Card text", Image(...))
        builder.withAskForPermissionsConsentCard(listOf(...))
    
        // Display templates
        builder.addRenderTemplateDirective(...)

        // etc.
    }
}

Learn more about available response builders here.

Using SSML

Alexa supports Speech Synthesis Markup Language enabling you to control how Alexa generates the speech. For example, you can add pauses and other speech effects.

To use these SSML tags in your scenarios you can use it directly or via helper functions:

reactions.say("Hello there! $break500ms Let's listen this audio ${audio("https://address/audio.mp3")}")

Learn more about available SSML helpers here.

Using AWS Lambda and DynamoDB

Amazon provides an AWS Lambda serverless cloud that can host your Alexa voice skills. It’s also possible to use a built-in DynamoDB database to store skill’s persistent data during its work.

For most developers, the Lambda free tier is sufficient for the function supporting an Alexa skill.

JAICF powered Alexa skills are ready to be deployed to AWS Lambda with DynamoDB support. Please learn how to use AWS Lambda and DynamoDB with your JAICF projects here.

It’s also a ready to use example that shows the complete project that can be deployed to AWS Lambda.