algolia / algoliasearch-alexa

🔊 Search by voice in Alexa, powered by Algolia

Table of Contents generated with DocToc

• Algolia Alexa Skills Kit Adapter
  • Quick start guide
  • API Description
    • algoliaAlexaAdapter
      • Handlers Configuration
        • Without Querying Algolia
        • Querying Algolia
      • State Management
      • Localization
  • Dev
  • Linting

Algolia Alexa Skills Kit Adapter

This is an adapter that allows you to use the Algolia search API easily within your Alexa Skills Kit Skill. It provides tools for integrating Algolia search and a framework for structuring your Alexa skill.

Developed to be used on Amazon Lambda, you set up your intent handlers normally except for any that you want to leverage Algolia. For these handlers, a configuration object must be provided that defines the handler you want to call upon completion of the Algolia search. Algolia will be queried automatically, then provide an object with the results, intent, session, and response to your defined handler.

Here you can see an example usage:

const algoliaAlexaAdapter = require('algoliasearch-alexa').default;

const handlers = {
  LaunchRequest () {
    this.emit(':tell', 'Welcome to the skill!');
  },
  SearchProductIntent: {
    answerWith (data) {
      if(data.results.nbHits) {
        this.emit(':tell', `There were ${data.results.nbHits} products found.`);
      } else {
        this.emit(':tell', 'We could find no products. Please try again.');
      }
    },
    params: {
      hitsPerPage: 1,
      filters (requestBody) {
        return `brand:${requestBody.request.intent.slots.brand.value}`;
      }
    },
  },
  CustomHelpIntent () {
    const speechOutput = 'Find one of 10,000 products from the Product Store, powered by Algolia.';
    this.emit(':tell', speechOutput);
  },
  Unhandled () {
    this.emit(':tell', 'Look for products in the Product Store.');
  },
};

const voiceSearch = algoliaAlexaAdapter({
  algoliaAppId: 'applicationId',
  algoliaApiKey: 'publicSearchKey',
  defaultIndexName: 'products',
  alexaAppId: 'amzn1.echo-sdk-ams.app.[unique-value-here]',
  handlers,
});

module.exports = voiceSearch;

Quick start guide

Follow this guide to quickly start with Algolia and Alexa.

API Description

algoliaAlexaAdapter

This function accepts a single argument, which is a configuration object.

This configuration object accepts:

• algoliaAppId: The app ID from your Algolia application (required)
• algoliaApiKey: The public search key associated with your Algolia application (required)
• alexaAppId: Used to verify that the request is coming from your Alexa Skill, responding with an error if defined and requesting application does not match this ID; optional but recommended
• defaultIndexName: The index you want to query on Algolia (required)
• handlers: An object with your standard request (LaunchRequest, IntentRequest, or SessionEndedRequest) or built-in and intent handlers (required)

Handlers Configuration

Each handler can be configured in one of two ways. How it's configured depends on whether one wants to query Algolia first or not.

Without Querying Algolia

Specify a key-value pair where the key is the intent handler name and the value is a function. The function will accept no arguments, but has the current request information bound to this, provided by the Alexa service via Lambda.

Querying Algolia

Specify a key-value pair where the key is the intent handler name and the value is an object. That object contains a function answerWith which will be invoked following the Algolia search. This accepts one argument: an object with values for the keys of results from Algolia and event from the Alexa service.

State Management

States in the Alexa Skills Kit represent, roughly, different steps in the skill flow process. For example, there can be a state for starting a game, a state for being in the middle of a turn, and an empty state that represents the skill launch. You can read more here at the Alexa Skills Kit SDK README.

To define your states for each handler, provide an array of objects, with each that you want tied to a specific state to have a key of state:

const states = {
  SEARCHINGMODE: '_SEARCHINGMODE'
};

const handlers = [
  {
    NewSession () {
      this.handler.state = states.SEARCHINGMODE;
      this.emit(':ask', 'Welcome to the skill! What product would you like to find?');
    },
  }, {
    state: states.SEARCHINGMODE,
    'AMAZON.YesIntent': {
      answerWith (data) {
        // Do something...
      }
    }
  }
];

Localization

You can set your localization strings via the languageStrings option on the top level object. Within the intents, you will invoke them with this.t as normal. See here for more information on localizing a skill.

Dev

$ npm run dev

Linting

Lints using eslint:

$ npm run lint

Autofixer:

$ npm run lint:fix

algoliasearch-alexa's Issues

Support Alexa Skills Kit Node.js SDK Version 1.0.12

Recently released, see: https://github.com/alexa/alexa-skills-kit-sdk-for-nodejs/releases/tag/1.0.12

Note: in the meantime, the Alexa Skills Kit SDK can be passed as an option on initialization to override the default.

More in depth example or tutorial in readme

I think that it would be incredibly helpful to have a more in depth tutorial or example on how to integrate algolia with an alexa still.

I am very new to lambda and alexa, and find the docs lacking detail on how exactly to get this up and running with a skill.

It is unclear what additional code is needed to allow the code in the readme to sync up with an Alexa skill. Would really appreciate something more in depth. Thanks!

Fails on search without query

On searches/intents without a query (e.g. only using query params, like filters), there is a Cannot read property 'value' of undefined error. This is a result of buildHandlers expecting a slot named query.