Alexa Skill Tutorials

Introduction

In this tutorial, we will introduce how to configure a ChatFlow app to an Alexa skill. We will also walkthrough a simple Alexa skill that repeats user input.

Here is an example of the skill in action:




By the end of this tutorial, you will be able to:

  • Create an Alexa skill through the Amazon developer console
  • Create an Alexa Chatflow application
  • Understand structures of the Alexa In and Alexa Out nodes
  • Display help card on the Alexa companion app on your smart phone

Create a Copy Cat Echo skill

Echo Bot Tutorial Video




Warning

The Copy Cat demo uses AMAZON.LITERAL for a truly open-vocabulary speech recognition experience. However, starting November 16, 2016, Amazon will not certify skills that use AMAZON.LITERAL (but they still work as your own demo skills).

1. Create an Alexa Copy Cat Chatflow app

  1. Go to ChatFlow and create a new application using the sample application “Alexa Copy Cat Skill”:
_images/chatflow-copy-cat-app.png

This app listens on incoming message sent from your Echo device through the Alexa In node and replies it with the Alexa Out node.

  1. Deploy this app to register a webhook callback address through the Alexa In node:
_images/alexa-in-node.png
  1. Copy the “Final URL” onto your clipboard. It will be used later in Step Configuration.

Now let’s go to the Amazon developer console and register an Alexa skill there.

2. Create an Alexa Skill

We want to create a skill that repeats what user says. For those who have worked with an Alexa skill, you already know by default Alexa only gives you the intent type and slots, but not the whole utterances. So the trick here is to use the AMAZON.LITERAL slot type to make the whole utterance a slot.

  1. Log in to Amazon developer console and click “ALEXA” to get started with the Alexa Skills Kit:
_images/alexa-get-started.png

Skill Information

  1. In Skill Information, pick a skill name and invocation name:
_images/skill-info.png
  1. In Interaction Model, input the following Intent Schema:
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
{
   "intents": [
    {
       "intent": "SuperIntent",
       "slots": [
          {
             "name": "Text",
             "type": "AMAZON.LITERAL"
          }
       ]
    }
   ]
}

Here for the Interaction Model, we use the AMAZON.LITERAL to force Alexa to perform open vocabulary speech recognition, while everything will be tagged as a single SuperIntent.

Sample Utterances

  1. In Sample Utterances, enter these two lines:
SuperIntent {z|Text}
SuperIntent {z z|Text}

We use z and z z here to enable both single-word and multi-word recognition.

_images/interaction-model.png

Configuration

  1. Paste the “Final URL” from Alexa In node and choose the North America region:
_images/skill-config.png

Note

The AMAZON.LITERAL slot is only supported in US English, but not UK English or German (source). So please only select North America here. For migrating AMAZON.LITERAL, check out the migration guide to custom slots.

SSL Certificate

  1. Select the wildcard SSL certificate option (the second option):
_images/skill-ssl.png

Note

KITT.AI uses a wildcard SSL certificat.

Test

Note

Amazon provides a Voice & Service simulator before a skill is actually deployed. It is a great tool to help check and understand skill input and output.

  1. Test your application before deployment. Simply input “hello there” to inspect the output from your Chatflow app
_images/skill-test.png

Finishing up

  1. Fill in the forms from Publishing Information and Privacy & Compliance*.

Warning

Do not click “Submit for Certification”.

  1. Open up your Alexa companion app from cellphone. Under “Your skills”, you should see your Copy Cat skill.

Note

Unpublished skills are only available to you!

_images/skill-on-app.png

Alexa In and Out Nodes

This section of the tutorial provides insight into message structures of the Alexa In and Alexa Out nodes

Alexa In

The Alexa In node wraps an external request in msg.alexa, which follows the Alexa Request Format.

There are three types of requests:

  1. LaunchRequest: when you say “Alexa, open <skill invocation name>”. At this time, Alexa should play a welcome message or provide usage instructions. msg.kitt._skill_launched is set to true.
  2. IntentRequest: when you engage with a skill in a session. The very first message in this session has msg.alexa.session.new = true. The rest has it false. msg.kitt._session_started reflects this.
  3. SessionEndedRequest: when you explicitly asks Alexa to exit from session, such as by saying “exit”. msg.kitt._session_ended is set to true.

Additionally, msg.kitt also automatically sets:

  • msg.kitt._session_id from msg.alexa.session.sessionId, used by the Router.
  • msg.kitt._user_id from msg.alexa.session.user.userId, used by the Router.
  • msg.kitt._timeout (by default 30 seconds), used by the Router.
  • msg.kitt._access_token from msg.alexa.session.user.accessToken if it appears.

It’s the remote access token if user has enabled account linking.

We will discuss msg.NLU in 2. Intent Request and outgoing message structures in Companion App Card.

Alexa Out

The Alexa Out node sends a response back to the Alexa skill that called Alexa In node or Alexa NLU node.

The response format follows Amazon’s specification.

The response has the following properties:

  • version (string): the same as version in Alexa In request, otherwise 1.0
  • sessionAttributes (object): set from msg.kitt to persist across sessions.
  • response.outputSpeech optional (object): {type: “PlainText”, text: msg.payload}. However, if available, msg.alexa.outputSpeech is assigned to response.outputSpeech – this is helpful if users want to have SSML output.
  • response.card optional (object): set from msg.alexa.card if availalbe to hold a Card Object. More information can be found on the Card Object.
  • response.reprompt optional (object): set from msg.alexa.reprompt if availalbe to hold a Reprompt Object. More information can be found on the Reprompt Object Page.
  • shouldEndSession (boolean): true if session is ended, then your skill will close and not expect further user input.

Test your skill with an Echo

Now let’s use a real Echo device to test the Copy Cat app.

1. Launch Skill

You: “Alexa, open Copy Cat.”

Echo: “Welcome. This is an Alexa Echo skill.”

When a user explicitly launches a skill, msg.kitt_skill_launched is set to true, which is handled by the following enter node:

_images/launch-skill.png

2. Intent Request

You: “Alexa, ask Copy Cat to repeat what I said.”

Echo: “I heard repeat what I said.”

In companion Alexa app: a card shows up.

When user says “ask Copy Cat to repeat what I said”, the utterance repeat what I said is matched against Sample Utterances:

SuperIntent {z|Text}
SuperIntent {z z|Text}

Then msg.alexa.request will have the following intent property:

"intent": {
    "name": "SuperIntent",
    "slots": {
        "Text": {
            "name": "Text",
            "value": "repeat what I said"
        }
    }
}

Here we capture the whole utterance. By default the Alexa In node sets this utterance from msg.alexa.request.intent.slots.Text.value to msg.payload:

_images/alexa-in-node.png

Note

You can specify your own if you use a different Intent Schema.

Then when new utterances come, the On Intent enter node handles them ultimately echoing back the utterances:

_images/on-intent.png

The Repeat User state node defines how the outgoing messages look like:

_images/repeat-user.png

The final output from Alexa Out would follow the Alexa Response Format.

Companion App Card

Continuing on from the pervious step, your Echo will reply with:

Echo: “I heard repeat what I said.”

In addition, the companion app will show a card.

This is achieved by setting msg.alexa.card. msg.alexa.card follows the format of Card Object

Reprompt

If you do not respond, Alexa will reprompt you with:

“You gotta say it S-L-O-W-L-Y slowly.”

This is achieved by setting msg.alexa.reprompt. msg.alexa.reprompt follows the format of Reprompt Object.

Ask or Tell?

If you want the current session to end, then specify in a state node:

msg.kitt._session_ended = true;

Alexa would end current session without expecting another user input.

Otherwise, Alexa would be waiting for user input, and reprompt user if no user input is given.

More Advanced Tutorials

So far we have created an “Echo” skill called Copy Cat by forcing Alexa output the utterance verbatim. However, we did not deal with understanding the sentence at all. There are two ways to go from here:

The first opition is to simply plug in a KITT.AI NLU node to handle NLU ourselves:

_images/alexa-kitt-nlu.png

However, we do not recommend this way because Alexa’s speech output might not be perfect. Instead we suggest that you use Alexa’s own NLU with its language model smoothed out with in-domain utterances. We have created a more advanced tutorial next to demonstrate how this is done.