Creating An Alexa Skill That Calls An API

Introduction

 

Here is another article on custom Alexa skills. In this article, I am going to demonstrate how to create a custom Alexa skill on an Alexa Hosted node.js server that can actually call an API. For that, I will be creating a custom Alexa skill named space patrol. The Alexa skill will be making requests to answer questions such as how many astronauts are there in space right now. With the help of this skill, once a user invokes Alexa, Alexa will fetch information from the external API and in response tell the user about the number of astronauts in space.

 

The backend code required for the Alexa skill to work will be stored in a lambda function inside the Amazon developer console.

 

Creating an Alexa Skill

 

To create a new skill, first, we need to login into the Alexa developer console, we need to mention the unique skill name and select the default language according to our location.

 

 

After that, we can choose a model to add to our skill. To create custom skills, we can select the custom model.

 

 

We can also choose a method or a template to host the skill’s backend code inside a lambda function.

 

 

We can choose Alexa hosted node.js or python template. We can also mention our own endpoint or server to store backend resources for the required Alexa skills. The next step is to choose a template to add to our skill, which we customize later according to our need and click on the create skill button.

 

Now as a skill has been created, we need to make adjustments to the skill’s frontend. Now I will be creating intents and sample utterances to create skill’s frontend.

 

First, we need to mention the invocation name. Users say a skill's invocation name to begin an interaction with a particular custom skill.

 

 

Now we have to create intents:

 

 

Here, I have added a new intent named GetRemoteDataIntent along with some sample utterances such as how many people are in space, how many people are in space now, and how many people are currently in space. No slots and custom slot types are defined for this Alexa skill.

 

After creating a model for a particular skill, we can save and build the model by clicking on the save model and build the model button on the top.

 

JSON code for the above frontend is as follows:

{
    "interactionModel": {
        "languageModel": {
            "invocationName": "space petrol",
            "intents": [
                {
                    "name": "AMAZON.NavigateHomeIntent",
                    "samples": []
                },
                {
                    "name": "AMAZON.CancelIntent",
                    "samples": []
                },
                {
                    "name": "AMAZON.HelpIntent",
                    "samples": []
                },
                {
                    "name": "AMAZON.StopIntent",
                    "samples": []
                },
                {
                    "name": "GetRemoteDataIntent",
                    "slots": [],
                    "samples": [
                        "how many people are in space",
                        "how many people are in space now",
                        "how many people are currently in space",
                        "how many humans are in space",
                        "how many humans are in space now",
                        "how many humans are currently in space",
                        "how many astronauts are in space",
                        "how many astronauts are in space now",
                        "how many astronauts are currently in space"
                    ]
                }
            ],
            "types": []
        }
    }
}

Creating the backend resource for the Alexa skill

 

To create backend code inside a lambda function, we can write code inside the index.js node.js file. The code for the custom Alexa skill is as follows:

const Alexa = require('ask-sdk-core');

const GetRemoteDataHandler = {
  canHandle(handlerInput) {
    return handlerInput.requestEnvelope.request.type === 'LaunchRequest'
      || (handlerInput.requestEnvelope.request.type === 'IntentRequest'
      && handlerInput.requestEnvelope.request.intent.name === 'GetRemoteDataIntent');
  },
  async handle(handlerInput) {
    let outputSpeech = 'This is the default message.';

    await getRemoteData('http://api.open-notify.org/astros.json')
      .then((response) => {
        const data = JSON.parse(response);
        outputSpeech = `There are currently ${data.people.length} astronauts in space. `;
        for (let i = 0; i < data.people.length; i += 1) {
          if (i === 0) {

            outputSpeech = `${outputSpeech}Their names are: ${data.people[i].name}, `;
          } else if (i === data.people.length - 1) {

            outputSpeech = `${outputSpeech}and ${data.people[i].name}.`;
          } else {

            outputSpeech = `${outputSpeech + data.people[i].name}, `;
          }
        }
      })
      .catch((err) => {
        console.log(`ERROR: ${err.message}`);

      });

    return handlerInput.responseBuilder
      .speak(outputSpeech)
      .getResponse();
  },
};

const HelpIntentHandler = {
  canHandle(handlerInput) {
    return handlerInput.requestEnvelope.request.type === 'IntentRequest'
      && handlerInput.requestEnvelope.request.intent.name === 'AMAZON.HelpIntent';
  },
  handle(handlerInput) {
    const speechText = 'You can introduce yourself by telling me your name';

    return handlerInput.responseBuilder
      .speak(speechText)
      .reprompt(speechText)
      .getResponse();
  },
};

const CancelAndStopIntentHandler = {
  canHandle(handlerInput) {
    return handlerInput.requestEnvelope.request.type === 'IntentRequest'
      && (handlerInput.requestEnvelope.request.intent.name === 'AMAZON.CancelIntent'
        || handlerInput.requestEnvelope.request.intent.name === 'AMAZON.StopIntent');
  },
  handle(handlerInput) {
    const speechText = 'Goodbye!';

    return handlerInput.responseBuilder
      .speak(speechText)
      .getResponse();
  },
};

const SessionEndedRequestHandler = {
  canHandle(handlerInput) {
    return handlerInput.requestEnvelope.request.type === 'SessionEndedRequest';
  },
  handle(handlerInput) {
    console.log(`Session ended with reason: ${handlerInput.requestEnvelope.request.reason}`);

    return handlerInput.responseBuilder.getResponse();
  },
};

const ErrorHandler = {
  canHandle() {
    return true;
  },
  handle(handlerInput, error) {
    console.log(`Error handled: ${error.message}`);

    return handlerInput.responseBuilder
      .speak('Sorry, I can\'t understand the command. Please say again.')
      .reprompt('Sorry, I can\'t understand the command. Please say again.')
      .getResponse();
  },
};

const getRemoteData = (url) => new Promise((resolve, reject) => {
  const client = url.startsWith('https') ? require('https') : require('http');
  const request = client.get(url, (response) => {
    if (response.statusCode < 200 || response.statusCode > 299) {
      reject(new Error(`Failed with status code: ${response.statusCode}`));
    }
    const body = [];
    response.on('data', (chunk) => body.push(chunk));
    response.on('end', () => resolve(body.join('')));
  });
  request.on('error', (err) => reject(err));
});

const skillBuilder = Alexa.SkillBuilders.custom();

exports.handler = skillBuilder
  .addRequestHandlers(
    GetRemoteDataHandler,
    HelpIntentHandler,
    CancelAndStopIntentHandler,
    SessionEndedRequestHandler,
  )
  .addErrorHandlers(ErrorHandler)
  .lambda();

To receive request from the user, request handlers are created for each intent to handle. Inside each handlers, canHandle and handle functions are defined.

 

The canHandle() function is where you define what requests the handler responds to. The handle() function returns a response to the user. If your skill receives a request, the canHandle() function within each handler determines whether or not that handler can service the request.

 

In this case, GetRemoteDataHandler has been created. The canHandle() function inside GetRemoteDataHandler contains LaunchRequest as well as IntentRequest. The user can launch or invoke Alexa by saying open followed by the Invocation name which in this case is space petrol, which is a LaunchRequest. Alexa can also be invoked by saying “Alexa ask followed by invocation name and a sample utterance”. Therefore, the canHandle() function within the GetRemoteDataHandler will let the SDK know it can fulfill the request. In computer terms, the canHandle returns true to confirm it can do the work.

 

With the help of the handle() function inside GetRemoteDataHandler, Alexa will be making requests to answer questions such as "How many astronauts are there in space right now?"

 

Inside the skill, a function named getRemoteData is defined which is making the call to the API, and then it returns all the information. The information is returned inside the response variable as an argument of getRemoteData function inside GetRemoteDataHandler. There is a for loop inside the function, looping through each of those records that were returned. Alexa will be speaking back the names of each astronaut.

 

Output

 

 

As we can see from the output the skill has been invoked by saying “Alexa ask space petrol how many people are in space”. Alexa then calls an external API where all the information regarding the number of astronauts is available, fetches all the information, and speaks astronaut names in her response to the user.

 

Summary

 

In this article, I created a custom Alexa skill that calls an external API. I also defined the invocation name, intents, and sample utterances. I created a function that calls an external API and then fetches all the information needed to send back as a response to the user each time a user asks for it. Proper coding snippets along with the output for the backend of skill is also provided.