Amazon Alexa Skills Challenge and My Pocket

Update 21 Aug 2017

The skill is now open-source! Visit it on GitHub: github.com/carsonip/alexa-pocket

Intro

I don’t have much time for this blog post because I’ll be taking an early flight tomorrow. Maybe I’ll add something later.

Hackathon

To state the obvious, the hackathon is about building Alexa skills. I have submitted 2 entries: My Pocket and Tomato Helper. I’ll focus on My Pocket in this blog post.

My Pocket

The Alexa skill is about reading your saved pocket articles to you using Alexa. It can be really useful when you don’t have your computer or smartphone in front of you. Maybe ask Alexa to read you a saved article in Pocket as a bedtime story.

Since the skill is about users’ Pocket articles, users have to go through Pocket’s authentication such that Alexa has the permission to access the resources.

Implementation

The API service is hosted using Amazon Lambda. I realize how much easier to work without maintaining a server.

The 2 main parts of this project are authentication and the skill functions.

Interesting points / Problems

API Gateway & Lambda redirection

The authentication lambda function is available to users through Amazon API Gateway. The main function is to redirect users to the Pocket OAuth page then after authorization redirect users back to the lambda function and store the token.

One problem I run into is about redirecting users with API Gateway. The lambda function cannot simply return a different HTTP status code because API Gateway will override the status code, afaik. The solution is to configure API Gateway such that it can return a different status code conditionally, and the solution is explained here.

Alexa Account Linking

Alexa already has a fully functional and friendly Account Linking function. It eases the development of skills that use 3rd party services. I also find some useful examples in this post.

One of the trap is under implicit grant mode, the redirect url uses url fragment to pass data instead of query string. It is really hard to spot this error because of the 1 character difference.

Pocket API

Pocket provides a friendly API which makes things easy. The Article View API is one of the APIs used in this project. It retrieves the content from Pocket articles which enables the skill to read them aloud. It is private but developers can apply for it. I would like to thank the Pocket team for being very responsive and supportive.

Misc

• Alexa has a response size limit. It forces the skill to chop the article content into small parts within the limit in order to work. Note that session attributes are also included in the response, therefore they contribute to the response size too.
• Just realize there’s a HTML parser called cheerio. It is lightweigh and fast. What’s better is that it uses jQuery syntax which makes it very easy to use. It is used for extracting the text out of the Pocket Article View API’s response.
• Certain characters are not allowed in SSML and Lambda logs do not reflect the error well enough. It is shown in the Alexa web app though. Characters &<” will mess up the SSML. In the W3C specification it says The use of double quotes, ampersand, and less-than characters is currently incompatible with SSML DTD usage. A simple fix (or hack) looks like this:

function ssmlEscape(speech) {
    speech = speech.replace(/&/g, ' and ');
    speech = speech.replace(/</g, '');
    speech = speech.replace(/"/g, '');
    return speech;
}

• Lambda functions should be versioned. I mess with the production version of the Lambda function and I start getting poor reviews of my skill :)