alexa-ruby
Ruby toolkit for Amazon Alexa service
AlexaRuby
Since I have now some spare time, I plan to completely revise this project and make it at least up to date with the latest Alexa custom skills API.
Maybe even more.
Originally forked from damianFC’s AlexaRubykit, this gem implements a convenient back-end service for interaction with Amazon Alexa API.
Installation
To install and use gem in your project just add this to your Gemfile:
gem 'alexa_ruby'
And bundle it with:
$ bundle install
Or install it as a separate gem:
$ gem install alexa_ruby
Docs
| Resource | URL |
|---|---|
| Amazon Alexa Skill Kit docs | https://developer.amazon.com/public/solutions/alexa/alexa-skills-kit/docs/alexa-skills-kit-interface-reference |
| Rubydoc | http://www.rubydoc.info/gems/alexa_ruby |
| Source | https://github.com/mulev/alexa-ruby |
| Bugs | https://github.com/mulev/alexa-ruby/issues |
Usage
Gem provides a possibility to easily handle requests from Amazon Alexa service and build responses to given requests.
Getting started
AlexaRuby usage is quite simple, to start you need to require gem in your ruby
file and pass it JSON request from Amazon Alexa service.
Here and below all examples will be based on Roda routing tree framework, but
you can use any other – AlexaRuby is a framework independent gem.
require 'roda'
require 'alexa_ruby'
class App < Roda
route do |r|
r.post do
r.on 'alexa' do
alexa = AlexaRuby.new(r.body.read)
end
end
end
end
Request structure validations can be disabled:
AlexaRuby.new(request, disable_validations: true)
If needed, you can validate request signature and Amazon SSL certificates chain. To do so specify several parameters:
AlexaRuby.new(
request,
certificates_chain_url: url,
request_signature: signature
)
After initializing new AlexaRuby instance you will have a possibility to access all parameters of the received request.
General request parameters
| Access path | Description |
|---|---|
| alexa.request.json | given JSON request |
| alexa.request.version | request version, typically “1.0” |
| alexa.request.type | request type, can be :launch, :intent, :session_ended or :audio_player |
| alexa.request.id | request ID |
| alexa.request.timestamp | request timestamp |
| alexa.request.locale | request locale |
Session parameters
Notice that user data exists in two scopes – session and context.
| Access path | Description |
|---|---|
| alexa.request.session.id | session ID |
| alexa.request.session.attributes | array with all session attributes |
| alexa.request.session.end_reason | session end reason, can be :user_quit, :processing_error or :user_idle |
| alexa.request.session.error | hash with session error info |
| alexa.request.session.state | current session state, can be :new, :old or :ended |
| alexa.request.session.user.id | skill user ID |
| alexa.request.session.user.access_token | user access token if account linking is enabled and user is authenticated |
| alexa.request.session.user.permissions_token | user permissions token |
Context parameters
Notice that user data exists in two scopes – session and context.
| Access path | Description |
|---|---|
| alexa.request.context.app_id | Alexa application ID |
| alexa.request.context.api_endpoint | Alexa API endpoint |
| alexa.request.context.user.id | skill user ID |
| alexa.request.context.user.access_token | user access token if account linking is enabled and user is authenticated |
| alexa.request.context.user.permissions_token | user permissions token |
| alexa.request.context.device.id | user device ID |
| alexa.request.context.device.interfaces | interfaces, supported by user device |
Intent request parameters
| Access path | Description |
|---|---|
| alexa.request.intent_name | given intent name |
| alexa.request.dialog_state | state of dialog with user, can be :started, :in_progress or :completed |
| alexa.request.confirmation_status | user confirmation status, can be :unknown, :confirmed or :denied |
| alexa.request.slots | array with all slots from intent |
Audio player request parameters
| Access path | Description |
|---|---|
| alexa.request.playback_state | current playback state |
| alexa.request.playback_offset | current playback offset in milliseconds |
| alexa.request.error_type | playback error type |
| alexa.request.error_message | playback error message explaining error |
| alexa.request.error_playback_token | audio player token of failed playback |
| alexa.request.error_player_activity | audio player activity in moment of failure |
Building response
To build a response take your freshly initialized alexa and start using alexa.response methods.
Add session attributes
It is possible to add one attribute to session scope:
alexa.response.add_session_attribute('key', 'value')
Exception will be raised if attribute already exists in the session scope.
If you want to overwrite it, call:
alexa.response.add_session_attribute('key', 'value_2', true)
You can also add a pack of attributes. To overwrite all existing ones call:
alexa.response.add_session_attributes(key: 'value', key_2: 'value_2')
To add new attributes and save existing ones call:
alexa.response.merge_session_attributes(key: 'value', key_2: 'value_2')
Add card
Supported card types are: Simple, Standard and LinkAccount.
card = {
type: 'Standard', title: 'Test', content: 'test',
small_image_url: 'https://test.ru/example_small.jpg',
large_image_url: 'https://test.ru/example_large.jpg'
}
alexa.response.add_card(card)
Add audio player directive
Supported directives:
- AudioPlayer.Play
- AudioPlayer.ClearQueue
- AudioPlayer.Stop
To start the whole new playback call:
params = { url: 'https://my-site.com/my-stream', token: 'test', offset: 0 }
alexa.response.add_audio_player_directive(:start, params)
To enqueue new audio file call:
params = { url: 'https://my-site.com/my-stream', token: 'test', offset: 0, play_behavior: :enqueue }
alexa.response.add_audio_player_directive(:start, params)
To replace all previously enqueued audio files call:
params = { url: 'https://my-site.com/my-stream', token: 'test', offset: 0, play_behavior: :replace_enqueued }
alexa.response.add_audio_player_directive(:start, params)
To clear all:
alexa.response.add_audio_player_directive(:clear)
To clear only enqueued tracks and keep the playing one:
alexa.response.add_audio_player_directive(
:clear,
clear_behavior: :clear_queue
)
To stop playback call:
alexa.response.add_audio_player_directive(:stop)
Get current state of response encoded in JSON
alexa.response.json
Add output speech to response
Ask user a question and wait for response (session will remain open):
question = 'What can I do for you?'
alexa.response.ask(question) # will add outputSpeech node
alexa.response.ask(question, question) # outputSpeech node and reprompt node
alexa.response.ask(question, question, true) # outputSpeech node, reprompt node and both will be converted into SSML
alexa.response.ask!(question) # will add outputSpeech node and return JSON encoded response object
Tell something to user and end conversation (session will be closed):
speech = 'You are awesome!'
alexa.response.tell(speech) # will add outputSpeech node
alexa.response.tell(speech, speech) # outputSpeech node and reprompt node
alexa.response.tell(speech, speech, true) # outputSpeech node, reprompt node and both will be converted into SSML
alexa.response.tell!(speech) # will add outputSpeech node and return JSON encoded response object
Testing
Run all tests with:
$ rake test
Please, feel free to open an issue in case of any bugs.
Contributing
You are always welcome to open an issue with some feature request or bug report. Also you can add new features by yourself. To do so, please, follow that steps:
- Fork master branch of this repo
- Add a new feature branch in your forked repo and write code
- Write tests
- Add pull request from your branch to alexa_ruby develop branch
All development is made only in develop branch before being merged to master.
License
AlexaRuby is released under the MIT license.