Alexa Skills - Rest API Using HTTP

This story is how I used an existing Rest API that was available and added Alexa Voice engine for my Rasberry Echo. By using Alexa I was able to have her dictate the text and allow her to enter manually the desired question/rest api calls, as well as allowed the response to also be spoken and displayed visually on the app.

If you have not ever created skill than I highly recommend going through the Amazon Skill to create a "Trivia Skill" to get a basic understanding of how the services work and how the intents match up to the lambda functions.

This example will help show you how Lambda Functions can communicating with the Rest API to get the desired text response.

Where does the Rest API fit in the Alexa flow?

1. Alexa [Wake Word], ask 'Gospel Library' to Read Matthew 10 14

2. Attempts to match Invocation Name to the skill from those enabled on the device to match 'Gospel Library' from your developer.amazon.com/alexa

3. Once it matches the Invocation Name then the 'Intent' will be matched based on the text provided after the Invocation Name. 'Read Matthew 10 14'

4. This then matched my intent named: ReadBookChapterVerseIntent. Which sends the request to aws.amazon.com/lambda with the provided paramters mapped in the sample utterances.

5. The function is then started whether that is the welcome or the specific intent in this is called because of the 'onIntent' function in the lambda function.

6. The onIntent then triggers the `function ReadBookChapterVerse(intent, session, callback)`

7. In the ReadBookChapterVerse function we do a few things:

• Initialize default variables

• Set function variables from the intent (intent.slots.book then .value)

• Checks valid variables provided otherwise asks for re-prompt

• Store sessions variables

• Using Node.JS and var http = require('http');

• Executes webRequest

• Resolves webrequest data to then return speech result or re-prompt

8. Text is then sent to the Alexa Skill to be read on Alexa Device and also create a card tile for iOS/Android Alexa app.

CODE

Here is the highlighted code blocks that made this all possible and allowed me to recieve the data from Alexa -> developer.amazon.com -> aws.amazon.com/lambda -> rest api -> aws.amazon.com/lambda -> developer.amazon.com -> Alexa/phone app

Intent Schema

{ 
 "intents": [ 
   { 
     "intent": "RandomScriptureMasteryIntent" 
   }, 
   { 
     "slots": [ 
       { 
         "name": "book", 
         "type": "BOMBOOKS" 
       }, 
       { 
         "name": "chapter", 
         "type": "AMAZON.NUMBER" 
       }, 
       { 
         "name": "startVerse", 
         "type": "AMAZON.NUMBER" 
       }, 
       { 
         "name": "endVerse", 
         "type": "AMAZON.NUMBER" 
       } 
     ], 
     "intent": "ReadBookChapterVerseIntent" 
   }, 
   { 
     "slots": [ 
       { 
         "name": "startVerse", 
         "type": "AMAZON.NUMBER" 
       }, 
       { 
         "name": "endVerse", 
         "type": "AMAZON.NUMBER" 
       } 
     ], 
     "intent": "ReadNextVerseIntent" 
   }, 
   { 
     "intent": "AMAZON.HelpIntent" 
   }, 
   { 
     "intent": "AMAZON.StopIntent" 
   }, 
   { 
     "intent": "AMAZON.CancelIntent" 
   } 
 ] 
} 

Custom Slot

BOMBOOKS

1 Nephi 
1st Nephi 
2 Nephi 
2nd Nephi 
Jacob 
Enos 
Jarom 
Omni 
Words of Mormon 
Mosiah 
Alma 
Helaman 
3 Nephi 
3rd Nephi 
4 Nephi 
4th Nephi 
Mormon 
Ether 
Moroni 
Exodus 
Leviticus 
Numbers 
Deuteronomy 
Joshua 
Judges 
Ruth 
1 Samuel 
1st Samuel 
2 Samuel 
2nd Samuel 
1 Kings 
1st Kings 
2 Kings 
2nd Kings 
1 Chronicles 
1st Chronicles 
2 Chronicles 
2nd Chronicles 
Ezra 
Nehemiah 
Esther 
Job 
Psalms 
Proverbs 
Ecclesiastes 
Song of Solomon 
Isaiah 
Jeremiah 
Lamentations 
Ezekiel 
Daniel 
Hosea 
Joel 
Amos 
Obadiah 
Jonah 
Micah 
Nahum 
Habakkuk 
Zephaniah 
Haggai 
Zechariah 
Malachi 
Matthew 
Mark 
Luke 
John 
Acts 
Romans 
1 Corinthians 
1st Corinthians 
2 Corinthians 
2nd Corinthians 
Galatians 
Ephesians 
Philippians 
Colossians 
1 Thessalonians 
1st Thessalonians 
2 Thessalonians 
2nd Thessalonians 
1 Timothy 
1st Timothy 
2 Timothy 
2nd Timothy 
Titus 
Philemon 
Hebrews 
James 
1 Peter 
1st Peter 
2 Peter 
2nd Peter 
1 John 
1st John 
2 John 
2nd John 
3 John 
3rd John 
Jude 
Revelation 
DC 
Doctrine and Covenants  

Sample Utterances

Lambda Function (GospelLibraryReader)

function sendWebRequest(inBook, chapter, startVerse, endVerse, cardTitle, callback) 
{ 
   var _this = this; 
   var sessionAttributes = {}; 
   var book = resolveBook(inBook); 
   sessionAttributes = createCurrentVerseAttributes(book, chapter, endVerse); 
   var url = 'http://bomapi-happycloud.rhcloud.com/v1/verses/' + book + '/' + chapter + '/' + startVerse + '/' + endVerse; 
   console.log("Requesting: " + url); 
   http.get(url, function(res){ 
               res.setEncoding('utf8'); 
               res.on('data', function(chunk){ 
                   var resultArray; 
                   if(chunk) 
                       resultArray = JSON.parse('' + chunk); 
                   else 
                       _this.console.log('Unable to resolve web request to happycloud.') 
                   if(resultArray) 
                       _this.console.log('array ' + resultArray + " length: " + resultArray.length); 
                    var scriptureResult = ''; 
                    if(resultArray) 
                       for (var i = 0; i < resultArray.length; i++) { 
                           _this.console.log(i + ' ' + resultArray[i]); 
                           scriptureResult = scriptureResult + " " + resultArray[i].book_title + " " + resultArray[i].chapter_number + ":" + resultArray[i].verse_number + " " + resultArray[i].scripture_text; 
                       } 
                   repromptText = "Please ask me to tell you a verse by saying, Read 1st Nephi 3 verse 7"; 
                   if(scriptureResult) 
                   { 
                       speechOutput = scriptureResult; 
                       callback(sessionAttributes, 
                           buildNextSpeechletResponse(cardTitle, speechOutput, repromptText, false));    
                   } 
                   else 
                   { 
                       speechOutput = 'I was unable to find ' + book + ' ' + chapter + ':' + startVerse + '. Please try another scripture'; 
                       callback(sessionAttributes, 
                           buildSpeechletResponse(cardTitle, speechOutput, repromptText, false));       
                   } 
               }); 
       }).on('error', function (e) { 
           speechOutput = 'I was unable to find ' + book + ' ' + chapter + ':' + startVerse + '. Please try another scripture'; 
           repromptText = 'Please ask me to tell you a verse by saying, Read 1st Nephi 3 verse 7'; 
           callback(sessionAttributes, 
               buildSpeechletResponse(cardTitle, speechOutput, repromptText, false)); 
       }); 
} 

Configure Test Event

Execute

For my specific case I was trying to support reading text from this rest api described here: https://tech.lds.org/forum/viewtopic.php?t=23076 This Rest API was setup and ready for my consumption. However there needed to be a few tweaks to it but overall everything went without any issues. I hope you have a similar result in using an existing Rest API.