Debugging your Alexa Skill

Hosting a skill for the Amazon Alexa platform can be more or less involved, depending on the implementation language and hosting platform you pick. If you have some experience with the Java-Servlet life-cycle, then implementing a skill in Java, using Amazon’s Alexa-Skills-Kit library for Java, available in this Maven Repository and on Github, becomes an easy task.
Mainly to show how to setup a gradle based web-application project for an Alexa-Skill, I have put together a “Hello-World” kind of Alexa-Skill (available on Github) that can perform very simple calculations. E.g., “Alexa, ask Calculator what is seventeen divided by five”.

I have created a few slides around this Hello-World Calculator example and try to explain how to evolve the intent schema out of sample utterances and also list the built-in slot-types and build-in intents.

Building Alexa Skills with the JAVA AlexaSkillsKit SDK

The idea however is that an Interaction Model (Intent Schema, Custom Types (dictionaries), and Sample Utterances) gets uploaded into Amazon’s Alexa Service, using the Amazon Developer Portal, while your Java code, handling the users’ intents and creating the responses are complied and bundled into a Java WAR file that is hosted at AWS or any other hosting provider.
Your web service must be available over a secure SSL connection, which may require an SSL certificate. Go back to my previous posts here and here, where I explain how to most conveniently acquire and deploy an SSL certificate.

Initially, it’s not all that difficult, to develop a skill for the Amazon Alexa platform, but after declaring more intents and handling them appropriately, the complexity can grow rather quickly, at least if (some) intents are interconnected.
Logging is essential, but being able to debug requests as they are comping in from the Amazon Alexa Service, can really speed-up the development process. Remote debugging into AWS seems rather involved and since many of us don’t have a static IP address and/or work behind a corporate firewall, running the Web-Server that is hosting your business logic web service on your development machine, seems almost impossible. However, there is way …


Here are the things you should have.

  • A domain name (e.g. ‘’) you have full control over, I currently prefer Google as my registrar.
  • An SSL certificate for that domain. I gladly pay sslmate the $16, for the convenience of getting a certificate that works everywhere.
  • A Java Web server (e.g. Tomcat) configured with that SSL certificate (see above) and able to accept HTTPS requests
  • An ngrok Pro account, which will cost you $10 per month.

Ngrok a localhost proxying service fully support TLS and provides a secure tunnel to your localhost, so you can run a personal cloud services from your own private network, even behind your corporate firewall.

Here are the steps to configure all components

  • In the Amazon Developer Portal, set your skill’s Service Endpoint (e.g. ‘’)
  • Start at your Ngrok Dashboard and register your domain name. When you enter your domain (e.g. ‘’) you will get a CNAME assigned in return, e.g. ‘’
  • Change the domain name mapping of your domain. Create or change the CNAME record and point your domain to the CNAME provided by ngrok. I’d use a very short TTL (1m), allowing you to quickly revert, if you want to.
  • Download and install ngrok on your development machine and while you are there, also copy your authtoken from the Ngrok Dashboard and register it on your machine. E.g., ./ngrok authtoken 656QXR7W5kmU89rwFxSpN_3sgVzes49NdvZk6Hm9tvB
  • Finally launch the tunnel:
    ./ngrok tls 8843
  • Configure your IDE, which hopefully is IntelliJ Idea, and run/debug your Web app for instance on (a non-privileged) port 8843.

In summary, your domain name is now mapped with a CNAME record into the domain and the Amazon Alexa Service will send an encrypted JSON document, containing the encoded intent and slots to the ngrok server.
Your development workstation has created a tunnel to the same ngrok server that just received an request from Amazon. The request (still fully encrypted) is now pulled down to your workstation and forwarded to localhost:8443, where it is decrypted and processed.

.. happy debugging ..

Leave a Reply