Link your Amazon Alexa Skill with a Google API within 5 minutes

Amazon Alexa has been a centre of attraction of the inquisitive developer community who have been trying their hands on developing skills for Alexa. But people have been facing problems when it comes to integrating their Alexa skill with a Google API. I don’t know what Google has on search queries with Alexa, they’ve been redirected to Google’s home page. This article is just an attempt at helping you out with a successful integration with a Google API. In this article I have used Google Sheets API v4. Let’s get started!

I presume that you have your skills development environment all set up. If you haven’t configured yours yet, take help with this article only for the skill and the lambda function (if you’re using one) integration and follow this tutorial to learn to code for a Lambda function in NodeJS. You might need help with this small change in the tutorial and you’d be good to go. In the tutorial, they try to call a function as this.AskQuestion which would return an undefined output. This can be solved by rewriting the AskQuestion function as,

function AskQuestion(attributes) {
    var language = attributes.language;
    var currentQuestion = flashcardsDictionary[attributes.currentFlashcardIndex].question;
    return "In "+ language+" "+ currentQuestion;
}

And then calling the AskQuestion as,

if (this.attributes.currentFlashcardIndex < DECK_LENGTH) {
  message += "Here is your next question. " + AskQuestion(this.attributes);
  this.response.speak(message).listen(AskQuestion(this.attributes));
}

Now, you know how to code a Lambda function and have a basic skill already set up. We need to now understand how the OAuth2 framework works. OAuth2 is a simple architecture to understand. There is basically a client (your skill), a resource owner(the users), a resource server (Google Sheets) and a authentication server (Google OAuth). The following diagram might give you better understanding of the framework.

Looking at the diagram, the authorisation request is a the login page which authorises the user’s credentials and returns a authorisation grant code. In turn when the application sends the grant code to the authorisation server which returns a refresh/access token pair. This access token is sent to the resource server with the resource request where it gets verified and the appropriate response is sent to the client. This access token has a lifetime of one hour by default, so when the access token expires the refresh token is sent to obtain a new access token and the request-response process continues. To get a better understanding of the OAuth2 framework visit google’s OAuth2 playground. This site could be used to debug usual request response issues like we do while building websites using Postman-like softwares.

After understanding how the OAuth2 framework works, we can now register an API with the Google’s API console. Follow the steps below to do so.

Step-1: Use this wizard to register your project or select one if you already have created a project. Click continue and go to credentials.

Step-2: On the Add credentials to your project page, click the Cancel button.

Step-3: At the top of the page, select the OAuth consent screen tab. Select an Email address, enter a Product name if not already set, and click the Save button.

Step-4: Select the Credentials tab, click the Create credentials button and select OAuth client ID.

Step-5: Select the application type Web Application and click the Create button.

Step-6: Click OK to dismiss the resulting dialog.

Step-7: Click the download icon (Download JSON) button to the right of the client ID. Save this file as client_credentials.json.

Now you need to follow the steps below to link your Google API to your Alexa Skill.

Step-1: Go back to your Alexa Skill dev console and click on the Account Linking option to the bottom left of your screen. This will open up a form.

Step-2: Go ahead and turn account linking on and select Auth Code Grant type. Fill in the form using the credentials from the client_credentials.json file you downloaded. (leave the client authentication scheme set to recommended HTTP Basic).

Step-3: Go to Google API Explorer or just google API explorer and select the API you need to use with your Alexa skill and turn Authorize requests using OAuth2.0 on which open a dialogue box which would ask some scoped to be checked on. Check the required and copy the same.

Step-4: Go back to your Alexa Skill dev console and paste the scopes. Copy the redirect URLs from below in the same form.

Step-5: Go back to Google developer’s console. Click on Credentials from the navigation column on the left and click on your OAuth2.0 client and paste the redirect URLs one by one then click save.

After this you can test account linking using the Amazon Alexa app on your phone. Account linking is successfully set up if you get the success message. Go ahead and test your alexa skill from the dev console, try saying anything. If account linking is working you’ll be able to see the accessToken being passed in the JSON alexa skill request. You can see that in the adjacent picture below “userId”.

Note- If the accessToken is not passed in the request, try disabling enabling your skill from the app. Let me know if it doesn’t work.

You have successfully enabled account linking with your Alexa skill if you have reached here. Now you need to handle the accessToken within your skill request in the Lambda function. The thing that Alexa does best is to handle the inside business with the OAuth2.0 involving access tokens, refresh tokens and authorization codes. You just need to handle the access tokens meant to be sent with your API requests to fetch data from the resource server.

In the Lambda code of your skill, whenever you need to request data from the resource server, go to that specific intent and get the access token from the skill request like,

Follow the directory of the access token from the alexa skill request. This access token is then sent with the API request header as,

Notice that the URL should follow the format given in the documentation and the references. Here, the URL follows a Google Sheets API format which fetches a range of values from a spreadsheet in the users Google Account. You can always use the Google OAuth2.0 playground to see the response format. This will help you structure the response for your Alexa Skill.

Let me know for issues and queries. Thank You.