alexa-rails is a ruby gem which is a mountable rails engine that will add abilities to your Ruby on Rails application to handle Amazon alexa requests and responses.
Do the usual by adding the following to your
The gem provides migrations that are needed to use few features of the gem. For example: Saving or reading the user's skill usage count. To generate the migrations, run the following
$ rails generate alexa:migrations $ rake db:migrate
config/initializers/alexa.rb and add the following configuration
Alexa.configure do |config| # Location permissions type config.location_permission_type = :country_and_postal_code # or full_address # Default title used on the display cards for your skill config.default_card_title = "My Alexa skill" # Add ID of your skills. Used for request verification config.skill_ids = [ "amzn1.ask.skill.xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx" ] end
Mount the engine for routes handling in your routes
# config/routes.rb Rails.application.routes.draw do ... mount Alexa::Engine, at: "/alexa" end
This will make you Rails app accept
POST requests from Alexa at
This has to be provided as the HTTPS endpoint URL for the skill.
To handle an intent, you will have to create an intent handler class.
For example, if your intent is named
PlaceOrder, you will have to create
the following file under you
module Alexa module IntentHandlers class PlaceOrder < Alexa::IntentHandlers::Base def handle ... response # intent handlers should always return the +response+ object end end end end
All intent handlers should contain a
#handle method that has required logic
as to how to handle the intent request. For example, adding session variables,
setting response to elicit slots, delegate etc.
#handle method should always return the
response object in available in the scope of
See [Handling Amazon's Built-in Intents / Other request types] section to see how to handle Amazon's built-in intent and other requests types.
Adding session variable:
session.merge!(my_var: value) # Accesssing session variable session[:my_var]
Depending on your conditions, you can set the reponse to elicit a specific slot and the respecitve views are used.
#handle is expected to return an instance of
Alexa::Response or its subclasses.
In normal cases, the
response object is returned.
In cases where the slots elicitation is delegated to alexa, an instance of
Alexa::Responses::Delegate has to be returned.
def handle ... return Alexa::Responses::Delegate.new end
The content for SSML and display cards is not set in the intent handler
We follow rails convention and expect all response content for intents to be
in their respective
default view files.
Also, the views are context locale dependant.
Given an intent named
PlaceOrder, you view files would be
In case of slot elicitations, follow a similar convention but make sure you
text files with the same name as the slot that is being
elicited. For example, in the
PlaceOrder intent, the elicatation for
slot would have the following views
Render custom template instead of default
If you wish to force the
response object to take contents from a different
template file instead of
default.*.erb, pass the custom filename with
For example: Instead of
default, if you wish to render the contents of
no_results.text.erb, return the response by forcing
the template with the following:
def handle ... return response.with(template: :no_results) end
and make sure you add your contents in the
no_results.*.erb files in your
intent handlers' views' directory.
By default, there is no re-prompt SSML is added to the response.
However, re-prompt SSML can be set in the ssml view of the intent response or
a slot elicitation view with a
content_for :repromt_ssml like this:
What is your address? <% content_for :repromt_ssml do %> Where would you like the pizza to be delivered? <% end %>
Type & Title
By default, the card type is set to
To change the card type and title, use the
content_for blocks in the
view file for the response as follows:
<% content_for :card_type do %> Simple <% end %> <% content_for :card_title do %> Get your pizza <% end %>
To render a permission card. Use
ask_for_permissions_consent as the
and provide the scope in
permissions_scope content_for block.
Following is an example for Device address permission card.
<% content_for :card_type do %> ask_for_permissions_consent <% end %> <% content_for :permissions_scope do %> read::alexa:device:all:address <% end %>
Note: The permission card should not have any other content other than the
Handling Amazon's Built-in Intents / Other request types
Requests for Amazon's built-in intents and other request types are also handled with intent handlers. Below is the mapping for every request type and respective intent handler classes. These intent handlers are not included in the gem as they are a but specific to the application. Refer to the table below and implement the intent handlers.
|Intent name||Handler class|
Other request types:
|Request type||Handler class|
|Session end request||
Add this line to your application's Gemfile:
And then execute:
Or install it yourself as:
$ gem install alexa
Contribution directions go here.
The gem is available as open source under the terms of the MIT License.