Advanced: Writing for Alexa (Intents)

Writing an Alexa skill on Dexter is just as easy as writing a bot for any of existing text platforms. In this guide to writing a bot script for Alexa, we'll share the ways in which Alexa differs from other platforms and how to adapt your script to work for Alexa!

Quick Reference

Intents vs. Keywords

When a user says a phrase to your Alexa skill, Alexa tries to map the meaning of that phrase to the best match in a list of special keywords we call intents. They then let Dexter know which intent keyword was the best match and we use that intent to figure out how the skill should respond given your bot script.

Since we match on intents instead of raw text for Alexa, your triggers should be the name of the intent (or in specific cases, the name of the request type) instead of a pure keyword match.

+ intentname
- I am an Alexa skill!

This also means that in the Message Logs, a user will be shown as having said IntentName, as opposed to the user's real message.

To write an Alexa skill that matches on raw text instead of on intents, try out our experimental CatchAll Mode.

The rest of this walkthrough assumes CatchAll Mode is not turned on and an Interaction Model has been provided by the user... read on to learn what that means.

Talking to Alexa

To activate an Alexa skill, a user must first say the skill's invocation name to begin an interaction with the skill. In order to open a skill with the invocation name "Number Trivia", a user might say any of the following phrases:

 Alexa, ask "Number Trivia" for a fun fact on the number 42.
 Alexa, talk to "Number Trivia" and give me a random number fact.
 Alexa, open "Number Trivia".
 Alexa, close "Number Trivia"

Depending on what the user says, your bot will need to respond appropriately. To do so, you need to understand what the user's request is. Each of the user's possible phrases can fall into one of three request types:

LaunchRequest

This request type is sent when the user tries to open an Alexa skill without an intent.

 Alexa, open "Number Trivia".

In this scenario, Alexa knows that the user would like to interact with your skill, but do not know how to proceed next. To respond to this type of request, include a response for the launchrequest trigger in your bot script:

+ launchrequest
- Welcome to the Number Trivia skill! Tell me a number and I will tell you a fun number fact.

IntentRequest

This request type is sent when the user says something to your skill that matches a provided intent:

 Alexa, ask "Number Trivia" for a random number fact

In this scenario, Alexa knows that this phrase is an IntentRequest that matches the RandomNumberFact intent. To respond to this request, include a response for the randomnumberfact trigger in your bot script:

+ randomnumberfact
- 42 is the number of museums in Amsterdam (Netherlands has the highest concentration of museums in the world).
- 10 is the highest score possible in Olympics gymnastics competitions.
All intents in triggers still follow the standard trigger restriction: they must be lowercase and stripped of punctuation.

How does Alexa know how to match an intent to an incoming user input? We go into more depth on this in the "Crafting an Interaction Model" section.

SessionEndedRequest

This request type is sent when an Alexa skill is closed or when the user fails to respond.

 stop talking

By default, we leave every session open. This means that after a bot responds, it will wait for the user to say something that might match a LaunchRequest or IntentRequest type. If the user does not respond in time (within 8 seconds), the session will close and Alexa will alert you that the skill has been closed.

When you want your skill to respond to this type of request, include a trigger for SessionEndedRequest request type and then let us know that you would like to close the session by including the ^alexaEndSession() shortcode.

+ sessionendedrequest
- No more number trivia for you, goodbye! ^alexaEndSession(true)

Crafting an Interaction Model

Alexa understands the logic of your skill from the Interaction Model configuration you provide in your skill's Alexa console page.

By providing this information, Alexa can identify the intent or the meaning of an incoming user input, as well as any slots or incoming bits of data from the user input that are relevant to save for use later.

Amazon's Built-in Intents & Slots

Amazon provides a set of built-in Intents for common actions that you can implement in your skill without requiring sample utterances.

Once again, all intents in triggers still follow the standard trigger restriction: they must be lowercase and stripped of punctuation.

When using these intents in your skill, be sure to follow the strict trigger restrictions expected for Dexter. That is, if you would like to use the AMAZON.StopIntent to handle a user saying they want to "close Number Trivia", you will need to include a trigger + response pair, like so:

+ amazonstopintent
- Alright, no more number facts for you! ^alexaEndSession(true)

Amazon also provides built-in Slot Types, like "AMAZON.DATE" and "AMAZON.NUMBER", which you can use to recognize and handle data that matches this type.

Inside the Interaction Model

The Interaction Model consists of three required fields:

  1. Intent Schema: This JSON object includes an array of intent objects and any slots associated with that intent.
  2. Custom Slot Types: For any other slots that you want to capture that do not fall in this list of built-in Slots, you will need to define the Slot Name, as well as examples of values for this Slot.
  3. Sample Utterances: a list of possible user inputs mapped to the intent they are associated with. Alexa uses this to figure out what intent matches incoming user input.

Alexa's documentation extensively explains how to craft an Interaction Model. Configuring your Interaction Model and saving it on your skill's app page is necessary before you can begin testing your Alexa skill.

For our Number Trivia skill, the associated Interaction Model might look as follows:

Number Trivia Skill: Intent Schema
{
  "intents": [
    {
      "intent": "RandomNumberFact"
    },
    {
      "intent": "GetNumberTrivia"
      , "slots": [
        {
          "name": "Number",
          "type": "AMAZON.NUMBER"
        }
      ]
    },
    {
      "intent": "AMAZON.StopIntent"
    }
  ]
}
Number Trivia Skill: Custom Slot Types

This skill has no custom slots and makes use of the built-in Amazon.NUMBER Slot type.

Number Trivia Skill: Sample Utterances
RandomNumberFact give me a random number fact
RandomNumberFact tell me random number trivia
RandomNumberFact random number facts
GetNumberTrivia fun fact on {Number}
GetNumberTrivia fact for {Number}
GetNumberTrivia {Number}

Speaking With Feeling

Any response that you write will automatically be handled in Speech Synthesis Markup Language (SSML). This syntax is helpful if you want additional control on how Alexa enunciates the speech given in your response.

+ talktoskillintent
- I want to tell you a secret. <amazon:effect name="whispered">I am not a real human.</amazon:effect>. Can you believe it?

Since Alexa cannot send multiple messages (or delay sending of a message), if you include a <send> or a <delay> tag in your response, we will replace them with appropriate SSML alternatives:

Saving Slots

If you have defined an intent schema that includes intents with associated slots, Alexa will return back any recognized Slots to Dexter. We save these slots in namespace variables, prefixed by _alexa_, for access in your botscript.

In the above Intent Schema, we capture an Amazon.Number value (i.e. a number) in the "Number" Slot. We can now access this number from our bot script by getting the _alexa_Number variable.

As you're drafting these responses for your Alexa skill, you can still make use of all of the magic from other Dexter features. See how we use the HTTP Request Syntax to make a call to a Numbers Fact API below with this variable:

+ getnumbertrivia
$ GET http://numbersapi.com/<get _alexa_Number>
- The number fact for <get _alexa_Number> is ${{__text}}

Alexa-Specific Shortcodes

We have a few new Alexa-specific shortcodes that help manage your Alexa session and enhance your bot script.

Publishing Your Skill

When you are ready to release your skill to the public, make sure your skill sufficiently handles the requirements of this Submission Checklist.