Update the Store API

We will start by updating our store API to add another end point that will take the order number and return the order status. To keep things simple, let’s add some logic so that if the order status is in a range of 1000-1999, we will return a response that the order is in a processing state. For an order number in the range of 2000-2999, we will return a response that the order is shipped with an expected delivery date. Any other order number will return a response that the order is not found.

app.get('/orders/:orderNumber/status', function (req, res) {
  const orderNumber = req.params.orderNumber;

  if (orderNumber >= 1000 && orderNumber <= 1999) {
    res.status(200).send({
      status: 'PROCESSING'
    });
  } else if (orderNumber >= 2000 && orderNumber <= 2999) {
    res.status(200).send({
      status: 'SHIPPED',
      estimatedDeliveryDate: new Date()
    });
  } else {
    res.status(404).send({ code: 404, messasge: 'NOT_FOUND' });
  }
});

Setup a new Alexa Skill

Now that we have an end point, let’s setup a new app in the Amazon Development Portal.

Goto Amazon Development Portal and create an account if you do not have one.

Select the Alexa option from the top menu and then click on the Alexa Skills Kit ‘Get Started’ button. Click on the ‘Add a New Skill’ button.

{
  "intents": [
    {
      "intent": "GetOrderStatus",
      "slots": [
        {
          "name": "OrderNumber",
          "type": "AMAZON.NUMBER"
        }
      ]
    }
  ]
}

{
  "intents": [
    {
      "intent": "GetOrderStatus",
      "slots": [
        {
          "name": "OrderNumber",
          "type": "AMAZON.NUMBER"
        }
      ]
    },
    {
      "intent": "AMAZON.CancelIntent"
    },
    {
      "intent": "AMAZON.HelpIntent"
    },
    {
      "intent": "AMAZON.StopIntent"
    }
  ]
}

GetOrderStatus what is the status of my order number {OrderNumber}
GetOrderStatus what is the status of my order {OrderNumber}
GetOrderStatus my order {OrderNumber} status
GetOrderStatus status of order {OrderNumber}

Update bot engine

Since we are not using the Aamzon Lambda to host our service, we need to do a little bit extra work. To make our skill accessible to public, we need to submit our skill for certification and to pass the certification our bot engine has to verify that all the incoming requests are valid and are coming from Amazon. This is to avoid someone else calling and using our service pretending to be Amazon. To verify incoming request, we need to check the validaity of the certificate, request a timestamp, and request a signature. You can read more about it in the ‘Alexa Skills Kit Security Testing’ section.

Thankfully, there are node modules that we can use with our service to verify Alexa requests. For Node.js app we can use the alexa-verifier module to verify all incoming requests, but since we are using Express, we can use alexa-verify express middleware - [alexa-verify-middleware] (alexa-verifier-middleware).

Install and add ‘alexa-verifier-middleware’ to package.json:

npm install --save alexa-verifier-middleware

Next, update index.js to use alexa-verify-middleware:

...
const avm = require('alexa-verifier-middleware');

app.use(avm());

app.set('port', (process.env.PORT || 5000));
app.use(bodyParser.urlencoded({ extended: false }));
app.use(bodyParser.json());

...

Now, all of the incoming request will be verified. Remember to load ‘alexa-verifier-middleware’ before any other body parsing middleware.

Next, we need to add a new endpoint '/alexa-webhook,’ which we used in our skill service URL configuration.

Add the following code in index.js:

app.post('/alexa-webhook', function(req, res) {
 console.log('Incoming request', req.body.request);
 res.send({
        version: '1.0',
        response: {
            outputSpeech: {type: 'PlainText', text: 'Hello World'},
            shouldEndSession: true,
        },
        sessionAttributes: {}
    });
});

Here we added a new endpoint to handle a POST request on the '/alexa-webhook’ route and respond with a simple hello world message.

Let’s quickly look at the response. Here the version field is Alexa API version set to ’1.0’. The sessionAttributes field defined here as an empty object, can take a list of key-value pairs and can be used to maintain data between different requests for the same session.

In the response object, the outputSpeech object is used by Alexa to voice output the response. In our sample response, we are setting the outputSpeech type to ‘PlainText.’ The other supported type is ‘SSML’ (Speech Synthesis Markup Language), which is a markup language for speech synthesis SSML offers better control on how Alexa will convert the text to speech. When using PlainText type, the outputSpeech object should have a ‘text’ field, similarly for ‘SSML’ type outputSpeech, which should have an ’ssml’ field with output text. The respone object also includes a boolean flag shouldEndSession field to end or keep the session active.

Other than the fields we defined in our sample response, the response object can have have a cards object that defines the card to render to the Amazon Alexa App, the reprompt object that defines the outputSpeech to re-prompt a user to respond, and a directive array with specific device-level actions to take using particular interface.

Please refer to Alexa Skill Kit Interface Reference for more details

Let’s update our bot engine to handle these requests.

First, let’s update our store-api.js and add another method to the retrieve order status:

const retrieveOrderStatus = (orderNumber) => axios.get(`${API_BASE_URL}orders/${orderNumber}/status`);

module.exports = {
  getSizes: sizes,
  getGender: genders,
  retriveProducts,
  retrieveOrderStatus
}

Next, let’s create a new file, alexa-bot-engine.js, with all of the logic to handle incoming requests from Alexa:

const axios = require('axios');
const storeApi = require('./store-api');

const ALEXA_API_VERSION = '1.0';

const buildResponse = (outputSpeech, shouldEndSession = true, sessionAttributes = {}) => {
    return {
        version: ALEXA_API_VERSION,
        response: {
            outputSpeech,
            shouldEndSession,
        },
        sessionAttributes
    }
};

const sendAlexaHelpMessage = (res) => {
    res.send(buildResponse({ type: 'PlainText', text: 'Hi, Awesome Tshirt Store Alexa skill can help you check your order status. What is your order number ?' }));
}

const sendAlexaThankYouMessage = (res) => {
    res.send(buildResponse({ type: 'PlainText', text: 'Thank you for using the Amesome Tshirt Store Alexa skill.  See you next time' }));
}

const sendAlexaOrderStatus = (res, slots) => {
    const orderNumber = slots.OrderNumber.value;
    if (orderNumber) {
        storeApi.retrieveOrderStatus(orderNumber)
            .then(response => {
                const orderStatus = response.data;
                let responseText;
                if (orderStatus.status === 'PROCESSING') {
                    responseText = 'We are processing your order. Please check the status again later';
                } else {
                    responseText = `Your order is shipped and will be delivered on ${new Date(orderStatus.estimatedDeliveryDate).toLocaleDateString()}`;
                }
                res.send(buildResponse({ type: 'PlainText', text: responseText }));
            })
            .catch(function (error) {
                console.error('Unable to retrieve order status', error);
                res.send(buildResponse({ type: 'PlainText', text: `No order found with order number ${orderNumber}` }));
            });
    } else {
        sendAlexaHelpMessage(res);
    }
}

const intentHandler = {
    'GetOrderStatus': sendAlexaOrderStatus,
    'AMAZON.HelpIntent': sendAlexaHelpMessage,
    'AMAZON.StopIntent': sendAlexaThankYouMessage,
    'AMAZON.CancelIntent': sendAlexaThankYouMessage
}

const handleIncomingMessage = function (req, res) {
    const { request } = req.body;

    if (request.type == 'IntentRequest') {
        const { intent } = request;

        if (intentHandler[intent.name]) {
            intentHandler[intent.name](res, intent.slots);
        }
    } else if (request.type == 'LaunchRequest') {
        sendAlexaHelpMessage(res);
    }
}

module.exports = {
    handleIncomingMessage
}

Let’s quickly go through the code.

We have a handleIncomingMessage function to handle incoming requests from the Alexa voice service. We expose this method using modue.exports and make it accessible to other modules.

The Alexa request body contains a lot of details, like the Alexa API version sessionId. Information exists about the application and the user, session information is used to provide additional context about the request, and a context object provides information about the current state of the Alexa service and the device at the time of request. You can read about the Alexa skill request in detail here.

We are interested in the request object, which is part of the request body. This includes the request type, id, timestamp, and more. Alexa requests can use the following types:

• LaunchRequest - When a user invokes our skill with the invocation name and user voice input does not map to any intent.
• IntentRequest - When a user says something that maps to one of our intents.
• SessionEndedRequest - When a user ends the session or an error occured.

In the handleIncomingMessage function, we first check the request type. If the request is a LaunchRequest type, we send the user our static help message. If the request type is IntentRequest, we also recieve an intent object as part of the request, which contains the intent name and slots object. The slots object will have fields for each slot and value of the field set to a name-value pair for that slot.

Here is an example intent object. You will receive this if the user says something to invoke the GetOrderStatus intent with the OrderNumber slot value ’2222’.

"intent": {
    "name": "GetOrderStatus",
    "slots": {
        "OrderNumber": {
            "name": "OrderNumber",
            "value": "2222"
        }
    }
}

For the request type IntentRequest, we invoke different handler functions based on the intent name. The GetOrderStatus intent will be handled by the sendAlexaOrderStatus function. We check if the slot required to process the request is available or not. In this case, we check if the request contains the OrderStatus slot with a valid value. If the value is missing, we send the help message to the user. If there is an order number, we call the storeApi to retrieve order status, and we build an outputSpeech response accordingly.

We defined a constant intentHandler and use an object literal pattern to map the intent name with the method to handle it. So, for the intent GetOrderStatus, we want to invoke the sendAlexaOrderStatus function. When our service receives a Cancel or Stop intent request, we want to send a static thank you message to the user using the sendAlexaThankYouMessage function. Similarly, when we recieve a Help intent request we send a static help message to the user using the sendAlexaHelpMessage function.

We use the function buildResponse to build the JSON response as expected by the Alexa service. This function takes the outputSpeech object, and the shouldEndSession boolean flag and sessionAttributes object as parameters, and build the response object. If not provided, it will set shouldEndSession to true and sessionAttributes as an empty object.

Now, let’s update our index.js '/alexa-webhook’ to pass the incoming request to the alexa-bot-engine.

const alexaBotEngine = require('./src/alexa-bot-engine');

app.post('/orderstatus', function (req, res) {
    alexaBotEngine.handleIncomingMessage(req, res);
});

Now deploy these changes to Heroku and we are ready to test our skill.

Test skills

Amazon offers two tools to test our skill. Under your Alexa skill, go to the ‘Test’ tab.

• Voice Simulator - Voice Simulator can be used test how Alexa will speak some text in plain text or SSML.
• Service Simulator - Service Simulator can be used to test our service.

Let’s use the service simulator to test our bot engine, by entering the text, “What is the status of my order, one one zero zero ?” in the input text field and clicking on ‘Ask Awesome Tshirt Store.’ Alexa will generate a service request based on the entered utterance that will display the response received from our bot engine under service response.

You can also use echosim.io to test your skill. Echosim is an Alexa Skill testing tool. It is a browser based interface to Alexa. Simply login to echosim.io using your Amazon account. Then click and hold the microphone button and speak a command you like to test. Echosim.io will process and respond once you release the button.

Publishing skills

To make our skill accessible to the public, we need to submit the skill for certification. Simply go to the ‘Publishing Information’ tab and fill in the form:

• Category - Select a category that best describes the skill. Shopping for this case.
• Testing Instructions - Provide instructions to test the skill.
• Countries & Region - Select the countries and region you like the skill to be available in.
• Short Skill Description - Short description is displayed in the skill list in the Alexa App and can be up to 160 characters.
• Full Skill Description - Full description include details about the skill like its features, purpose, and how it works.
• Example Phrases - Provide some sample utterance to help users understand how to use the skill.
• Keywords - Provide comma separated keywords that describe the skill and help users find the skill.
• Images - Provide small (108108) and large (512512) icons in PNG that will be displayed in the Alexa app.

Once you fill in the form, click on the ‘Submit for Certification’ button. The Alexa team will review and test the skill and once approved it will be available for the public to use.