AlexaToolbox

This gem implements a full suite of tools for deploying applications for Amazon's Alexa.

Installation

For Ruby Projects:

Add this line to your application's Gemfile:

gem 'alexa_toolbox'

And then execute:

$ bundle

Or install it yourself as:

$ gem install alexa_toolbox

Usage

This Gem provides methods to create and handle requests, create response objects, and miscellaneous support functions for Alexa skills.

Requests

Amazon Request Documentation

Handling Request JSON:

require 'alexa_toolbox'
request = AlexaToolbox::Request.new(params,{ :application_id => 'YOUR_APP_ID' })
# params variable is json request retrieved by server (default is params in Ruby on Rails)
# request application IDs are checked vs your application ID to ensure they are valid requests as per Amazon's guidelines

Check Request Validity:

You should always check request validity as per Amazon's guidelines Amazon Guidelines

require 'alexa_toolbox'
request = AlexaToolbox::Request.new(params,{ :application_id => 'YOUR_APP_ID' })
if !request.valid?
  # return 500 status
end

Getting Information From the Request

require 'alexa_toolbox'
request = AlexaToolbox::Request.new(params,{ :application_id => 'YOUR_APP_ID' })

request.type
# Returns request type: 
# LaunchRequest
# IntentRequest
# SessionEndedRequest
# AudioPlayer
# PlaybackController
# System.ExceptionEncountered

# Check if new session
request.session.new?
# Get sessionId
request.session.session_id
# Get userId
request.session.user_id

Utilizing Request Hash

If you are more comfortable navigating the request hash and are familiar with the setup you can still acces it.

require 'alexa_toolbox'
request = AlexaToolbox::Request.new(params,{ :application_id => 'YOUR_APP_ID' })

# Get Session
request.json[:session]
# Get sessionId
request.json[:session][:sessionId]

Alexa Documentation on Address Data

If you want to access the user's address, you'll first require their permission and then you'll receive a consent token and deviceId in the request. Once you have those, you will need to utilize Amazon's API to retrieve the address data. (Supporting feature a WIP.)

require 'alexa_toolbox'
request = AlexaToolbox::Request.new(params,{ :application_id => 'YOUR_APP_ID' })

consent_token = request.session.consent_token
device_id = request.session.device_id

Responses

Amazon Response Documentation

Simple Response Object Example:

require 'alexa_toolbox'
response = AlexaToolbox::Response.new
response.add_speech('Creating a response is so easy!')
response.build_response

If you want to utilize SSML (will add speak tags if you forget!):

require 'alexa_toolbox'
response = AlexaToolbox::Response.new
response.add_speech('Creating a response is so easy!',true)
# or
# response.add_speech('<speak>Creating a response is so easy!</speak>',true)
response.build_response

To add a card to your response:

require 'alexa_toolbox'
response = AlexaToolbox::Response.new
# add_card(type,title,content)
# or
# add_hash_card({ :type => type, :title => title, :content => content })
response.add_card("PlainText","Card Title","This card should have some interesting content for your user.")
response.build_response

Full Documentation

Request

Initialization:

request = AlexaToolbox::Request.new(json_request, {
  :application_id => 'SKILL_APP_ID'
})

json_request should be a valid JSON request object. If you are using Ruby on Rails, this will be the params variable in your controller. While :application_id in the options hash is not required, part of Amazon Alexa security best practices is to compare request applicationId against your skill's application id. As such, I recommend this is set and you check validity (see below) before going further. If you don't know where to find your application id, you can get it here: Get Your Application ID

.valid?

Check if the request is valid and intended for your application.

request = AlexaToolbox::Request.new(json_request, {
  :application_id => 'SKILL_APP_ID'
})
if request.valid?
  # continue with your skill logic
else
  # return 500 as per Amazon Alexa Documentation
end

.json

JSON representation of the request. Use this if you are familiar with the Alexa request structure and rules and don't wish to use AlexToolbox's request handling.

request = AlexaToolbox::Request.new(json_request, {
  :application_id => 'SKILL_APP_ID'
})
request_json = request.json

request.json[:version]
# "1.0"

.type

Return the type of request being made.

Possible Types: LaunchRequest IntentRequest SessionEndedRequest AudioPlayer System.ExceptionEncountered PlaybackController.NextCommandIssued

For AudioPlayer requests, it will return as "AudioPlayer" and not the full request type. AudioPlayer requests will have an .audioplayer object

request = AlexaToolbox::Request.new(json_request, {
  :application_id => 'SKILL_APP_ID'
})
request.type
# "IntentRequest"

.version

Return the version of the request (always "1.0" currently)

request = AlexaToolbox::Request.new(json_request, {
  :application_id => 'SKILL_APP_ID'
})
request.version
# "1.0"

.request_id

Return the requestId of the request

request = AlexaToolbox::Request.new(json_request, {
  :application_id => 'SKILL_APP_ID'
})
request.request_id
# "EdwRequestId.d2fb326f-337d-4ca9-b99b-c308d7cbf8dd"

.locale

Return the locale of the request ("en-US","en-UK",etc.)

request = AlexaToolbox::Request.new(json_request, {
  :application_id => 'SKILL_APP_ID'
})
request.locale
# "en-US"

.options

Read the options set for the request (this will house your application_id)

request = AlexaToolbox::Request.new(json_request, {
  :application_id => 'SKILL_APP_ID'
})
request.options
# { :application_id => 'SKILL_APP_ID' }

.session

Access information on the session, view the session section for more information on the session object. Is not included in AudioPlayer requests.

request = AlexaToolbox::Request.new(json_request, {
  :application_id => 'SKILL_APP_ID'
})
request.session

.intent

Access information on the intent, view the intent section for more information on the intent object. Is only included for requests with type "IntentRequest".

request = AlexaToolbox::Request.new(json_request, {
  :application_id => 'SKILL_APP_ID'
})
request.intent

.audioplayer

Access information on the audioplayer, view the audioplayer section for more information on the audioplayer object. Is only included for requests with type "AudioPlayer".

request = AlexaToolbox::Request.new(json_request, {
  :application_id => 'SKILL_APP_ID'
})
request.audioplayer

.error

Access information for errors. This is only included for requests with type "System.ExceptionEncountered" and "AudioPlayer". error has two keys, :type and :message.

request = AlexaToolbox::Request.new(json_request, {
  :application_id => 'SKILL_APP_ID'
})
request.error
# { :type => "MEDIA_ERROR_INVALID_REQUEST", :message => "Alexa recognized the request as being malformed. E.g. bad request, unauthorized, forbidden, not found, etc." }

.cause

Access information for error cause. This is only included for requests with type "System.ExceptionEncountered". cause has one keys, :requestId.

request = AlexaToolbox::Request.new(json_request, {
  :application_id => 'SKILL_APP_ID'
})
request.cause
# { :requestId => "EdwRequestId.d2b326f-37d-4a9-b9b-c307cbf8d" }

.context

Access context information for the request, not always provided and may be phased out for most request types.

request = AlexaToolbox::Request.new(json_request, {
  :application_id => 'SKILL_APP_ID'
})
request.context

Session

Intent

Audioplayer

Context

Request

Address

DisplayDirective

You can display content on the new Echo Show using the predefined templates. Amazon Official Documentation Reference

Examples

BodyTemplate1 Example

  response = AlexaToolbox::Response.new
  display_directive = AlexaToolbox::DisplayDirective.new("BodyTemplate1","Winner")
  display_directive.template.add_title("You won!")
  display_directive.template.hide_back_button
  display_directive.template.background_image.set_content_description("Description of image")
  display_directive.template.background_image.add_source("https://placeholder.com/placeholder_image.jpg")
  response.add_display_directive_object(display_directive)

BodyTemplate3 Example

  response = AlexaToolbox::Response.new
  display_directive = AlexaToolbox::DisplayDirective.new("BodyTemplate3","SampleCard_92347")
  display_directive.template.add_title("Body Template Title Example")
  display_directive.template.hide_back_button
  display_directive.template.text_content.add_primary_text("Example of text content. This content contains <b>bold text</b>, <i>italics</i>, and <br/> line breaks.","RichText")
  image = AlexaToolbox::DisplayDirectiveImage.new("Mount St. Helens landscape","https://example.com/resources/card-images/mount-saint-helen-small.png")
  display_directive.template.add_image_object(image)
  response.add_display_directive_object(display_directive)

ListTemplate2 Example

  response = AlexaToolbox::Response.new

  display_directive = AlexaToolbox::DisplayDirective.new("ListTemplate2","list_template_two")
  display_directive.template.add_title("Pizzas")
  display_directive.template.hide_back_button

  list_text = AlexaToolbox::DisplayDirectiveTextContent.new
  list_text.add_primary_text("<font size='7'>Supreme</font> <br/> Large Pan Pizza $17.00","RichText")
  list_text.add_secondary_text("Secondary Text")
  list_text.add_tertiary_text("")
  list_image = AlexaToolbox::DisplayDirectiveImage.new("Supreme Large Pan Pizza","http://www.example.com/images/thumb/SupremePizza1.jpg")
  display_directive.template.add_item_to_list("item_1",list_image,list_text)

  list_text = AlexaToolbox::DisplayDirectiveTextContent.new
  list_text.add_primary_text("<font size='7'>Meat Lovers</font> <br/> Large Pan Pizza $17.00","RichText")
  list_image = AlexaToolbox::DisplayDirectiveImage.new("Meat Lovers Large Pan Pizza","http://www.example.com/images/thumb/MeatLoversPizza1.jpg")
  display_directive.template.add_item_to_list("item_2",list_image,list_text)

  response.add_display_directive_object(display_directive)

Troubleshooting

Contributing

Fork it
Create your feature branch (git checkout -b my-new-feature)
Commit your changes (git commit -am 'Add some feature')
Push to the branch (git push origin my-new-feature)
Create a new Pull Request

Please make sure to write specs for any new features!

Team Members

"Paul McMahon" [email protected]

AlexaToolbox

Installation

For Ruby Projects:

Usage

Requests

Handling Request JSON:

Check Request Validity:

Getting Information From the Request

Utilizing Request Hash

Utilizing Address Consent

Responses

Simple Response Object Example:

If you want to utilize SSML (will add speak tags if you forget!):

To add a card to your response:

Full Documentation

Request

Initialization:

.valid?

.json

.type

.version

.request_id

.locale

.options

.session

.intent

.audioplayer

.error

.cause

.context

Session

Intent

Audioplayer

Context

Request

Address

DisplayDirective

Examples

BodyTemplate1 Example

BodyTemplate3 Example

ListTemplate2 Example

Troubleshooting

Contributing

Team Members