Amazon Alexa Platform Integration

The Amazon Alexa platform integration allows you to build custom Alexa Skills using Jovo.

Introduction

Apps for Alexa are called Alexa Skills. The official suite of services, frameworks, and APIs to build Alexa Skills provided by Amazon is called Alexa Skills Kit (ASK). You can find a general introduction into building Alexa Skills in the official Alexa documentation.

In the installation section, we're going to set up a Jovo project that works with Amazon Alexa.

An Alexa Skill usually consists of two parts:

  • The Alexa Skill project in the Alexa Developer Console
  • The code that handles the logic of your Skill

In the Alexa Developer Console, the Alexa Skill project is configured, including an Alexa Interaction Model that trains Alexa's language understanding service. Learn more about how to use the Jovo CLI to create and deploy Alexa Skill projects in the Alexa Developer Console project section.

If a user converses with your Skill, Alexa sends API requests to your Skill's code endpoint. The code is then responsible for returning an appropriate response. Learn more about how you can build this with the Jovo Framework in the Alexa Skill code section.

Jovo is a framework that allows you to build apps that work across devices and platforms. However, this does not mean that you can't build highly complex Alexa Skills with Jovo. Any custom Alexa Skill that can be built with the official ASK SDK can also be built with the Jovo Framework. In the platform-specific features section, we're going to take a look at building

Installation

To create a new Alexa project with Jovo, we recommend installing the Jovo CLI, creating a new Jovo project, and selecting Alexa as platform using the CLI wizard. Learn more in our getting started guide.

# Install Jovo CLI globally
$ npm install -g @jovotech/cli

# Start new project wizard
# In the platform step, use the space key to select Alexa
$ jovo new <directory>

If you want to add Alexa to an existing Jovo project, you can install the plugin like this:

$ npm install @jovotech/platform-alexa

Add it as plugin to your app configuration, e.g. app.ts:

import { App } from '@jovotech/framework';
import { AlexaPlatform } from '@jovotech/platform-alexa';
// ...

const app = new App({
  plugins: [
    new AlexaPlatform(),
    // ...
  ],
});

You can also add the CLI plugin to your project configuration in jovo.project.js. Learn more about the Alexa-specific project configuration here.

const { ProjectConfig } = require('@jovotech/cli');
const { AlexaCli } = require('@jovotech/platform-alexa');
// ...

const project = new ProjectConfig({
  // ...
  plugins: [
    new AlexaCli(),
    // ...
  ],
});

The Alexa CLI plugin uses the official ASK (Alexa Skills Kit) CLI provided by Amazon for deployment. For the deployment to work, you need to at least set up a default ASK profile using the ASK CLI. Follow the official Alexa docs to install and configure ASK CLI.

# Install ASK CLI globally
$ npm install -g ask-cli

# Configure ASK profile
$ ask configure

After the successful installation, you can do the following:

Alexa Developer Console Project

Jovo helps you manage your Alexa Skill project in the Alexa Developer Console using the Jovo CLI.

You can use the build command to turn the Alexa project configuration into Alexa specific files.

$ jovo build:platform alexa

These files can be found in a folder called platform.alexa in the build directory of your project. They include the Alexa Interaction Model that is responsible for training Alexa's natural language understanding service.

Since Alexa requires certain built-in intents, make sure that the files in your models folder contain the following elements before running build. They are added by default if you select Alexa as platform in the new CLI wizard.

{
  "alexa": {
    "interactionModel": {
      "languageModel": {
        "intents": [
          {
            "name": "AMAZON.CancelIntent",
            "samples": []
          },
          {
            "name": "AMAZON.HelpIntent",
            "samples": []
          },
          {
            "name": "AMAZON.StopIntent",
            "samples": []
          }
        ]
      }
    }
  }
}

The resulting files can then be deployed to the Alexa Developer Console using the deploy:platform command.

$ jovo deploy:platform alexa

Learn more on the following pages:

Alexa Skill Code

The Jovo Alexa platform package is a platform integration that understands the types of requests Alexa sends and knows how to translate output into an Alexa response. To learn more about the Jovo request lifecycle, take a look at the RIDR documentation.

When a user interacts with your Skill through Alexa, the voice assistant turns user input (usually speech) into structured meaning (usually intents and slots). It then sends a request with this data to you Jovo app. Learn more about the request structure in the official Alexa docs.

The Jovo app then uses this request information to return an appropriate response that tells Alexa what to say (or display) to the user. For example, the code snippet below asks the user if they like pizza:

LAUNCH() {
  return this.$send(YesNoOutput, { message: 'Do you like pizza?' });
}

If you want to learn more about how to return the right response, take a look at these concepts:

The output is then translated into a response that is returned to Alexa. Learn more about the response structure in the official Alexa docs.

Platform-Specific Features

The Alexa platform integration for Jovo supports a lot of platform-specific features. You can access the Alexa object like this:

this.$alexa;

You can also use this object to see if the request is coming from Alexa (or a different platform):

if (this.$alexa) {
  // ...
}

The following Alexa properties offer additional features:

User

There are various Alexa specific features added to the user class that can be accessed like this:

this.$alexa.$user;

The following features are offered by the Alexa user property:

User Profile

You can call the Alexa Customer Profile API to retrieve the user's email address like this:

await this.$alexa.$user.getEmail();

Below is an example getEmail handler:

async getEmail() {
  try {
    const email = await this.$alexa.$user.getEmail();
    return this.$send({ message: `Your email address is ${email}` });
  } catch(error) {
    if (error.code === 'NO_USER_PERMISSION') {
      return this.$send({
        message: 'Please grant access to your email address.',
        platforms: {
          alexa: {
            card: {
              type: 'AskForPermissionsConsent',
              permissions: [
                'alexa::profile:email:read'
              ],
            },
          },
        },
      });
    } else {
      // ...
    }
  }
},

If the getEmail call returns an error with the code NO_USER_PERMISSION, an AskForPermissionsConsent card (learn more in the official Alexa docs) is added to the Alexa-specific output. Please note that the example adds the output to the $send() method for simplicity. It could also be added using output classes.

Output

There are various Alexa specific elements that can be added to the output.

Learn more in the Jovo Output documentation for Alexa.

Entities (Slots)

Alexa slots are called entities in Jovo. You can learn more in the Jovo Model and the $entities documentation.

You can access the Alexa-specific $entities property like this, which allows you to get typed access to the native API result for each slot:

this.$alexa.$entities;

// Example: Get native API result object for slot "name"
this.$alexa.$entities.name.native;

Learn more about the structure of the API result in the official Alexa documentation on entity resolution.