If we are already friends, you will now I like to make API driven (headless) systems! Particularly connecting different systems, for example CMS content beyond just the website. Therefore when Umbraco announced their Headless service, I was intrigued to what could be done with it.
** This post is over a year old, so the tech is likely out of date **
Note: This was written when Umbraco Headless is in beta and therefore there is a good chance it may be out of date if you are reading at a later date.
I decided to try to integrate content from Umbraco Headless with an Amazon Alexa skill. Here is a video showing how it works.
Umbraco Headless - A cloud hosted Umbraco instance intended to provide info via API rather than a web frontend hosted in the same app. There are SDKs for .Net and Node.js. Sign up here: https://umbraco.com/headless/
Alexa Skills Kit - APIs and tools to help us build Alexa Skills. To get a basic understanding of the steps required to build a skill connecting the Alexa developers console with AWS lambda function, I would recommend following this tutorial... it can explain it way better than I can!
What are we making?
I decided to make a simple app that will give you a welcome message and let you choose between latest Umbraco news or information about Umbraco meetups. The content for these messages will all be content managed in Umbraco.
Setting up the voice UI
In Alexa skills development you configure your skill here: https://developer.amazon.com/alexa/console/ask. This is where you set up the voice user interface.
You need to configure several things:
* Invocation - This is how the user "opens" the application. (Mine is "headless")
* Intents - The actions that can occur when a user interacts with the skill.
* Utterances - The things the user can say to invoke the intent.
Lambda Function
The easiest way to host your custom code for Alexa skill is in AWS Lambda Functions, with it being an Amazon product they work well together and it is free for the purposes of development (limited calls). For this example I am using Node.js 8.10.
Follow these instructions:
* on your local machine, create a folder for your skill.
* create a package.json including the dependancies 'ask-sdk' and 'umbraco-headless'. My example package.json is on GitHub.
* create an index.js. My example code is on GitHub (We'll have a look at the code later).
* open cmd on that folder & run 'npm install'.
* zip the whole folder.
* In the lambda configuration, edit the "code entry type" field drop down, selecting "upload a .zip file". Select your .zip file.
Headless Umbraco
Here is my node structure within Umbraco:
Code
So let's finally have a look at how we use the Umbraco Headless SDK! I used the tutorial code references earlier and edited to work with headless sdk and the intents I need.
Headless config - this is where you put your specific headless config to allow it to connect to your headless umbraco instance:
Welcome Intent Handler - When the welcome intent is called (skill invoked) this is automatically called due to it handling "LaunchRequest".
News Intent Handler - When the News intent is called we get the news node, loops though the news items and add information to the speech output.
Meetups Intent Handler - When the Meetups intent is called we get the meetups node, loops though the items and add information to the speech output.
Testing
If you have a device, you can can test by saying "Alexa, open headless", alternatively you can test in the Alexa developer console where you have configured your skill.
Here's the output of my testing:
--------
Hopefully this helps, if you build anything cool in headless I would love to see it! Ping me on twitter