Welcome to Voxa’s documentation!

Summary

Voxa is an Alexa skill framework that provides a way to organize a skill into a state machine. Even the most complex voice user interface (VUI) can be represented through the state machine and it provides the flexibility needed to both be rigid when needed in specific states and flexible to jump around when allowing that also makes sense.

Why Voxa vs other frameworks

Voxa provides a more robust framework for building Alexa skills. It provides a design pattern that wasn’t found in other frameworks. Critical to Voxa was providing a pluggable interface and supporting all of the latest ASK features.

Features

  • MVC Pattern
  • State or Intent handling (State Machine)
  • Easy integration with several Analytics providers
  • Easy to modify response file (the view)
  • Compatibility with all SSML features
  • Works with companion app cards
  • Supports i18n in the responses
  • Clean code structure with a unit testing framework
  • Easy error handling
  • Account linking support
  • Several Plugins

Installation

Voxa is distributed via npm

$ npm install voxa --save

Initial Configuration

Instantiating a StateMachineSkill requires a configuration specifying your Views and Variables.

'use strict';
const Voxa = require('voxa');
const views = require('./views'):
const variables = require('./variables');

const skill = new Voxa({ variables, views });

Responding to alexa events

Once you have your skill configured responding to events is as simple as calling the skill.lambda method

const skill = require('./MainStateMachine');

exports.handler = skill.lambda();

Using the development server

The framework provides a simple builtin server that’s configured to serve all POST requests to your skill, this works great when developing, specially when paired with ngrok

// this will start an http server listening on port 3000
skill.startServer(3000);

Responding to an intent event

skill.onIntent('HelpIntent', (alexaEvent) => {
  return { reply: 'HelpIntent.HelpAboutSkill' };
});

skill.onIntent('ExitIntent', (alexaEvent) => {
  return { reply: 'ExitIntent.Farewell' };
});

Project Samples

To help you get started the state machine has a number of example projects you can use.

Starter Kit

This is the simplest project, it defines the default directory structure we recommend using with voxa projects and has an example serverless.yml file that can be used to deploy your skill to a lambda function.

My First Podcast

In this example you will see how to implement a podcast skill by having a list of audios in a file (podcast.js) with titles and urls. It implements all audio intents allowed by the audio background feature and handles all the playback requests dispatched by Alexa once an audio has started, stopped, failed, finished or nearly to finish. Keep in mind the audios must be hosted in a secure server.

Account Linking

A more complex project that shows how to work with account linking and make responses using the model state. It uses serverless to deploy your account linking server and skill to lambda, create a dynamodb table to store your account linking and create an s3 bucket to store your static assets. It also has a gulp task to upload your assets to S3