Amazon Alexa Skill with Umbraco CMS

18/06/2017 umbraco alexa headless webapi

At Umbraco Codegarden I gave a talk “Controlling content for the connected world” and ran an open circle session on IOT. The feedback from this has been great and people seem interested in getting started with IOT projects, and integrating with their existing Umbraco CMS knowledge.

** This post is over a year old, so the tech is likely out of date **

Since Codegarden I have been chatting to a few fellow Umbracians and we thought it would be cool to have a hackathon where we can work on IOT projects together.

I thought I would do a getting started guide to integrating Umbraco as a headless CMS to Amazon Alexa… Hopefully it helps!


Umbraco and WebAPI


First of all, let’s build the CMS and API side of things. I created a new solution in visual studio (Empty Project), then installed UmbacoCMS via NuGet. Full instructions on Umbraco documentation.

 Build and run the solution and you will be taken through the install process, I selected the option with no starter kit as I don’t need a front end to this site, it’s only going to be an API.

Once set up I set up a home node and a doctype to represent an Alexa device with a few fields for “Welcome Message”, “Unknown Message” and “UniqueId”.

Now it’s time to get this data via API, Umbraco docs here on how you can inherit from UmbracoAPIController to get an API endpoint.

Once I have this endpoint I can now get my Umbraco content and return it in JSON to be used by my Alexa skill.

See API controller here:


Alexa skill- an introduction


Here is some useful info from the Alexa documentation for a bit of background:

  • Different types of skill: custom skill, smart home skill and flash briefing skill. In this example I will be building a custom skill.
  • The requests your skill can handle are represented as intents.
  • Sample utterances map the intents to the words and phrases users can say to interact with your skill.

Way more information here on the Alexa skills kit site.


Alexa skill- basic tutorial


When I started on trying to build an Alexa skill, I done this tutorial , only difference is I selected the Node JS one rather than Python as if fits my skill set better. I won’t really say much here and the tutorial is pretty self explanatory. In the end you have a skill where you can tell it your favourite colour and it will remember it and repeat it to you when asked.

You don’t necessarily need to have an echo device to write a skill as you can test with the online tools. 


Alexa skill- Call an API


So you are probably thinking “Aye, very good Carole, you followed a tutorial” but that’s how I learn best. I take the sample code then mess with it til I get it to do what I want. Next, rather than have the welcome text be hardcoded, I want it to call my API to get it from Umbraco.

I found some sample code on how best to call and API in an Alexa skill here and added it to the tutorial code for Node JS Alexa skill. Based on this I edited the skill to call my API. I also passed in the applicationId from the session so we can have a separate response from our CMS depending on application.

See extract of my Alexa Skill code here

Now if we publish a change to content, it’s updated in our API response and therefore our Alexa Skill.


Testing Alexa


You can of course test on your echo device, but if you don’t have one you can till test on the developer portal.You can type in the command and you will see a JSON response and you can also hear it out loud as if it was Alexa’s voice too:

So this app doesn’t really do much, but hopefully this tutorial is a good starting point for getting Umbraco content into your Alexa skill. If you are interested in joining us in our IOT hacking, join us on the IOT channel on Umbraco Slack.


Next up: I will try and follow this up with a similar skill for a flash news briefing.


Any questions or feedback, let me know! Say hello on twitter.