Building Cross-Platform Voice Apps With VOXA — Part 2

This is the second part of a series on creating cross-platform voice apps with Voxa

Photo by Jacek Dylag on Unsplash

In the previous article, I briefly explained what you can do with Voxa, the voxa-cli tool, and the voice app we’re going to create at the end of this series.

In this article, we’re going to create Alexa Skills and Google Actions in your accounts. We’re going to create the spreadsheets that will rule the VUI (Voice User Interface) part of the app.

This is super helpful when you’re working in a team and others can collaborate to enhance your VUI. So, let’s get started!

You can use Google Spreadsheets to manage the VUI (Voice User Interface) of your voice app. Image via www.pixabay.com

First of all, we need to create a project using voxa-cli. You can find the npm package here. Open your terminal window on your computer and type:

npm i -g voxa-cli

This command will install the latest version of voxa-cli locally. When the command finishes, you can type:

voxa create

This will guide you step-by-step through setting up your project with some options:

Step-by-step assistant to create a Voxa project

You’ll be asked for your app’s name, the developer’s name, the platforms, and the programming language (JavaScript or TypeScript). Some of the final questions are related to the spreadsheets: interaction model, publishing information, and the canFulfill feature.

We’re also going to integrate our app with DynamoDB and Dashbot analytics, so make sure to respond Yes to those questions.

Now that our base code is created, let’s check it out! You can type in your terminal:

cd quick-maths; code .

This will leave the current folder in the root of your project and will open it using Visual Studio Code.

Basic structure of a Voxa project created with voxa-cli

Run npm install or yarn install to create the node_modules folder. In our case, we will use yarn.

The src/app folder is where we usually add the logic of the app. We’re going to work on this folder in the next article.

The src/app/index.js file is the starting point of the app. As we explained in part 1, Voxa is an MVC framework, so we will consider these key parts in the following files:

• Model: The src/app/model.js file. In every request to your project, you will have access to a model variable where you can call all the functions and access the variables of the model.
• Views: The src/app/views.json file. If you use the voxa-cli, this path will change to src/languageResources, where the tool will download the VIEWS from the interaction model spreadsheet including all locales. If you define variables for dynamic content, you can define these variables in the src/app/variables.js file. The values of these variables will be grabbed from the model (model.js file)
• Controllers: The src/app/states folder. You can define all intent and state handlers with the function voxaApp.onIntent and voxaApp.onState.

Basic structure of a state file in Voxa

I will be pushing my changes to this repository in different branches: part2, part3, part4, and part5:

The src/config folder is where you define the different environments of your app.

Voxa-cli adds two environment files: production and staging. You can define the environment you want to work with by setting the environment variable NODE_ENV to staging, production, or the environment you want.

The voxa-cli also allows you to download intents, utterances, and views from a spreadsheet.

There’s also another spreadsheet where you can define all the metadata info for your Alexa Skills: skill name, permissions, interfaces, descriptions, image (URL) keywords, etc.

For this app, I have already prepared two spreadsheets which are public and you can copy them to your Google Drive.

Follow this to access the publishing information spreadsheet.

Quick Maths publishing information spreadsheet

In the publishing information spreadsheet you’ll find three important tabs:

• SKILL_GENERAL_INFORMATION: Define all general metadata info for your Alexa Skill.
• SKILL_ENVIRONMENTS_INFORMATION: Define endpoints for Alexa and Dialogflow.
• SKILL_LOCALE_INFORMATION@en-US: Define locale-specific info like images, descriptions, keywords, or example phrases. You can create other tabs for other locales too, you just need to modify the suffix to the locale, like: @en-GB, @de-DE, @es-ES, or @it-IT.

Access the interaction model spreadsheet.

Quick Maths interaction model spreadsheet

In the interaction model spreadsheet you’ll find four important tabs:

• INTENT: Define all intents with their slots and types. There’s also a column to define Dialogflow’s events, like GOOGLE_ASSISTANT_WELCOME or actions_intent_CANCEL. You can also add intents specific to one platform or the other, set if an intent will be a startIntent (Dialogflow) or can use the CanFulfillIntent interface (Alexa) automatically.
• UTTERANCES_MAIN: Define all utterances for every intent you defined in the INTENT tab.
• VIEWS_FILE@en: Define all the responses of your voice app. You can define other locales, just like the SKILL_LOCALE_INFORMATION tab from the publishing information spreadsheet: @de, @it, @es, @ru-RU, etc.
• INVOCATION_NAMES: Define the invocation names for every environment you have. In our case, we have set quick maths for the production environment, and quick maths staging for staging.

Now, we need to modify the interaction.json file with the URLs of the spreadsheets. Take a look at this gist to see what your file should look like:

Basic structure of the interaction.json file

To download these resources, we need a key from Google Cloud. You can check the GitHub repository and follow the instructions to create the Google Cloud project.

When you download the key file, copy it to the root folder of your voice project, and name it client_secret.json. Now, you can run:

yarn interaction

This will download your utterances and responses. You will see three new folders:

• /src/content: Other content downloaded with voxa-cli. For example, the {environment}-canfulfill-intents.json files.
• /src/languageResources: Views downloaded from spreadsheet.
• /speech-assets: Interaction model for Alexa and Dialogflow.

You can double-check the progress of the project so far in this branch in the repository I’m using to push my changes as we follow the step-by-step instructions.

Now, it’s time to create the Skill and Action in your accounts. Go to the Amazon Developer Console and create a Skill called Quick Maths. And, in the Actions Console, create a Quick Maths Action.

For Alexa, go to the Build tab, and under the JSON Editor menu copy the /speech-assets/alexa/en-US/{environment}-interaction.json file contents, depending on the environment you’d like to set up first.

If you have set up the ASK CLI, you can run this command:

ask api update-model -s {SKILL_ID} -f speech-assets/alexa/en-US/production-interaction.json -l en-US

To update the Skill metadata, you can run

ask api update-skill -s {SKILL_ID} -f speech-assets/alexa/production-manifest.json

For Dialogflow, go to the Actions menu, click on the BUILD button, and go to the Dialogflow console.

You can zip the content of the /speech-assets/dialogflow/{environment}/ path and upload it to Dialogflow. Go to the settings button ⚙️ and click on the Export and Import tab.

Click on the RESTORE FROM ZIP button and drag the zip file from your project. Finally, go to the Integrations menu, click on the Google Assistant button and click on the TEST button.

Alexa’s Account Linking

Let’s start with Alexa. Go to the developer portal, in the top right of the page there’s a button with the initials of your account’s name, click on it and then click on Settings.

In this post from Alexa’s blog, you’ll see detailed step-by-step instructions on how to create your LoginWithAmazon configuration for account linking.

Step by step to create LoginWithAmazon configuration

Go to your Skill’s configuration in the developer portal console. Under the ACCOUNT LINKING menu, enable Account Linking and paste the following values:

Authorization URI: https://www.amazon.com/ap/oa
Access Token URI: https://api.amazon.com/auth/o2/token
ClientID: from LoginWithAmazon
ClientSecret: from LoginWithAmazon
Client Authentication Scheme: HTTP Basic
Scopes: profile, postal_code
Domain list: amazon.com, na.account.amazon.com

Google’s Sign In

Go to your Action’s configuration in the Actions console. Under the Account linking menu, follow these steps:

• Account creation: Select Yes, allow users to sign up for new accounts via voice.
• Linking type: Google Sign In.

Click on Save.

Step-by-step to set up Google Sign In

Final

With these two steps completed, we have finished the account linking integration for our voice apps. In the next article, we’ll create the logic for the game and the competition.

Thanks for reading! Be sure to check out the next articles.