Welcome to Voxa’s documentation!


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.


  • 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


Voxa is distributed via npm

$ npm install voxa --save

Initial Configuration

Instantiating a Voxa Application requires a configuration specifying your Views and Variables.

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

const app = new voxa.VoxaApp({ variables, views });


Once you have instantiated a platform is time to create a plaform application. There are platform handlers for Alexa, Dialogflow and Botframework (Cortana);

const alexaSkill = new voxa.AlexaPlatform(app);
const dialogflowAction = new voxa.DialogflowPlatform(app);

// botframework requires some extra configuration like the Azure Table Storage to use and the Luis.ai endpoint
const storageName = config.cortana.storageName;
const tableName = config.cortana.tableName;
const storageKey = config.cortana.storageKey; // Obtain from Azure Portal
const azureTableClient = new azure.AzureTableClient(tableName, storageName, storageKey);
const tableStorage = new azure.AzureBotStorage({ gzipData: false }, azureTableClient);
const botframeworkSkill = new voxa.BotFrameworkPlatform(app, {
  storage: tableStorage,
  recognizerURI: config.cortana.recognizerURI,
  applicationId: config.cortana.applicationId,
  applicationPassword: config.cortana.applicationPassword,
  defaultLocale: 'en',

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

Responding to an intent event

app.onIntent('HelpIntent', (voxaEvent) => {
  return { tell: 'HelpIntent.HelpAboutSkill' };

app.onIntent('ExitIntent', (voxaEvent) => {
  return { tell: 'ExitIntent.Farewell' };

Responding to lambda requests

Once you have your skill configured creating a lambda handler is as simple using the alexaSkill.lambda method

exports.handler = alexaSkill.lambda();