Last updated: June 19th, 2019

Introduction

Voicehub is a content management and analytics platform for voice based apps. In its core, Voicehub lets you manage the content your voice apps sends out to your users, and combines it with extensive analytical features.

Voicehub allows you to make dynamic changes to the content of your voice app and push it live in real time, while it also collects analytical metrics about the performance of your app, helping you understand how your voice app is being used.

Quick Start Video

Voice Apps

With Voicehub, you can manage multiple voice apps such as Alexa Skills and Google Actions in one place.

Create a new Voice App

To onboard a voice app onto Voicehub, you can create a new voice app on the Voice Apps Page of your Voicehub Account. Of course, you can also onboard any of your already existing Skills or Actions onto Voicehub. You can also create generic apps on Voicehub, which let you create exactly what you need. This is ideal for working with frameworks which have a single codebase for multiple platforms. In general, you can use this any time if your project does not fit the other two options.
Create new Voice App
App Name
Specify a name for your app, can be any name you like.
Type
Specify if this voice app is an Alexa Skill, Google Action or a generic app.
Locales
Select all the locales you are planning to support.
Default/Fallback Locale
Select a fallback locale which will be used in case of missing content.

You can then see your created voice app in the overview.

Voice App Overview
API Username
This is the username the developer who is implementing Voicehub needs to use when talking to the Voicehub API. Every voice app has its own API username.

Switch between Voice Apps

At any time, you can switch between your voice apps on the very top of the page. The content will change automatically.
Voice App Overview

You can switch between your voice apps anytime at the very top of the page.

Intents

Intents are the building blocks of a voice app. They act as a collection of content which deal with a specific query the user asked your voice app. For Alexa Skills and Google Actions, the default intents are automatically created for you after you create a voice app.

Intents Overview

Because all the content in a voice app is written for intents and the logic they deal with, the Intent Page acts as an overview page for your content on Voicehub. It gives you a visual overview of how your voice app looks like and where what content is returned to the user.

Intents Overview Page

Next to the default intents, you can create new intents on the overview page. Also, you can create new posts for intents right here.

Create new Intent

Adding a new intent is simple and straightforward.

Create new Intent
Intent Name
To keep it simple, give the intent on Voicehub the same name it has in your code and Alexa/Google config.
Description / Help Text
Write a few words describing the intent to identify it more easily later.

Models

Voicehubs content management system is based on models and posts. Models are defining how a post is structured, for example, what fields it can have. Models also ensure consistency and give the developer who is implementing Voicehub the confidence, that the content can be accessed as expected.

The Model Builder

To create a new model, check the Content Models Page. Add a model to open up the model builder.

Create new Voice App
Model Name
Give your content model a name.
Description / Help Text
Especially when multiple people work on the same voice app, it is incredibly helpful to have a small reminder what the model is about.

To start building the model, add a first field to it:

Create new Voice App
Field Name
Give this field a unique name. This name should be lowercase and not start with a number.
Description / Help Text
Describe the use of this field. When writing a post later, you will see this small reminder again helping you to better understand what you are editing.
Type
Voicehubs model builder provides multiple types for its content. They are explained in the following section.
Required
Enabling this field means that it is required to fill out this field in posts based on this model. Enabling this, you can be sure that this field will always be non-empty.
Localized
If you configured your voice app with multiple locales, enabling this will create separate input fields for this field for every locale you support.

You can add any kind of fields you like to a model using the model builder.

Create new Voice App

The model builder lets you create content models which your posts will be based on. Here you can see the fields of your model, add, edit or delete them.

Model Data Types

Each field in a model has a certain data type. The data type ensures that the developer can rely on the content he is retrieving and enables integration of many different types of content.

For example, you could build a voice app having several characters play against each other, and you could give them different strengths and weaknesses using numbers, like an attack speed value or a defensive value. Or with a recipe app, you can use the number type for ingredients.

Data Types

The data type you choose for a field determines the type of input you will get when you edit a post based on the model. It also determines the data type of the field for the developer.

Speech

API Datatype: string

Selecting speech for the data type will give you the possibility of writing SSML enhanced speech content with our SSML editor. You can also listen to the speech you just wrote by pressing the play button and having it read out by the corresponding Amazon or Google voice for your app. The editor is documented in detail in the editor section.

Voicehub SSML Editor

Number

API Datatype: number

When you select number as data type, you get a simple number input field. You can input both positive and negative integers (e.g. 7) and floats (7.25).

List

API Datatype: array

When you select list as type, you get another option to chose what the list will be composed of. You have two options here: list of speech and list of numbers.

List of Speech

With a list of speech, you get an ordered list of multiple SSML editors, allowing you to write ordered content.

List of Numbers

A list of numbers gives you multiple input fields for an ordered list of numbers.

Cards

API Datatype: object

You can of course build cards with Voicehub. Selecting this datatype will provide you with our card builder on every post based on this model. For Alexa, you can select between a simple card with just a title and a text body, or a standard card with title, text and an image. For Google Actions, the basic card exists, with a title, subtitle, text body and a button with a link. You may also use some formatting in the latter. Cards also support parameters in all text fields (except image urls and button properties).

Parameter

API Datatype: string

The parameter type allows you to make your content highly dynamic. When you add a parameter to a model, posts based on the model can use it inside the content. This way, you can dynamically create speech which changes based on the parameter input.

An simple example is asking the user for his age, and then using what he answered in the next turn. Or if you wish to include formulas, that is also possible. You could have a recipe model with a "portions" parameter, allowing you to dynamically calculate the required amounts in the speech and return it to the user.

Dynamic Parameters

As a content editor, you create a parameter you would like to use in the content. The developer integrating Voicehub then needs to provide a value for this parameter, which gets dynamically injected into your written speech content.

Once you declared a parameter in the model, you can use it in your content. You will get a little button for the parameter you defined in the editor. It's up to you how you want to use it, just make sure, a value for it will be provided when the post is requested. Also, if you are planning on writing a formula, the provided value should of course be a number.
Dynamic Speech Parameters

Use dynamic parameters in your speech content to make it more dynamic, inject phrases, numbers or results from API calls which are created on the fly.

Posts

Posts are the key pieces from which the content in your voice app is made up. Every post is based on a model, and every post belongs to an intent. A post can have multiple fields, depending on the model the post is based on. In addition, the post can have multiple localized versions of a field, if your voice app supports multiple locales and the field is localized.

Posts Overview

The Content Page gives you an overview of your posts.

Posts Overview

On the overview page, you can easily see which posts are used in which part of your voice app, and what models the posts are based on. Here you can also add new content to your voice app.

Create a Post

By clicking on the add post button, you can create a new post.

Create Post
Post Name
Give your post a unqiue name, helping you to identify it.
Model
Specify the model the post should be based on.
Intent
Select the intent the post belongs to.

You can then start writing your post. You will notice the switch at the top, where you can switch between the "live" and the "draft" stage.
Voicehub uses a live and draft stage system, allowing you to have a draft stored next to your live contents. As you type, Voicehub automatically saves your content separately as draft, so you will not loose anything and you can save your work for later.

Create Post

Once you are happy with your content, you can click "Publish Changes" to have the contents in the live stage overwritten by your edits in the draft stage.

Voicehub SSML Editor
Beta

Our SSML editor is a tool assisting you in creating great voice-first speech content. Is has multiple features allowing you to write visually flavoured SSML and also listen to an audio playback of what you just wrote.

Voicehub SSML Editor Features

SSML Type: break
Example: <break time="1s"/>

The break tool allows to you insert a pause between sentences or words in your voice content.

SSML Type: emphasis
Example: <emphasis level="strong">Voicehub<emphasis>

Put emphasis on words using the emphasis tool.

SSML Type: prosody
Example: <prosody speed="fast" volume="loud" pitch="high">Have fun!<prosody>

You can change volume, speed and pitch of your content using the prosody tool.

SSML Type: say-as
Example: <say-as interpret-as="spell-out">SSML<say-as>

Using the say-as tool, you can have speech interpreted differently, such as spelled out characters and numbers, or have the assistant read out fractions, telephone numbers or addresses as a human would do it.

The formula tool helps you to write any arithmetic expression with a parameter used in the post as variable, for example portions * 2, which will get calculated and injected into the speech when the post is retrieved with a value for the used parameter.

The parameter injection tool lets you insert parameters into your content when you want to use them as a stand-alone entity. You can also create new parameters on the spot. When the post is requested and a value for the used parameter is provided, it will get replaced with that value. If you have more complex requirements, consider using the formula tool as described above to write more complex logic involving dynamic parameters.

When you press play, the contents of the editor will be read out to you by the same engine your voice app uses. So if you work on an Alexa Skill, it will sound (almost) like Alexa by using Amazon Polly, and for Google Actions, it will utilize Googles Wavenet voices, which are also used in Google Actions.

Migration

Migration from typical Skill or Action setups to Voicehub is easy. First of all, you do not have to change anything about how you host your voice app. You can of course continue to use AWS Lambda, Google Firebase or your own solution for hosting your code. In order to make full use of Voicehub, you should however consider migrating the data from the database containing user data of your voice app. Not only can it be much cheaper to use Voicehub for managing your users, it also enables Voicehubs analytics features to the full extend and allows for the generation of reports and other insights.

Amazon DynamoDB Migration

In order to not interrupt the proper functionality of your existing Alexa Skill, you can easily copy over stored user data from DynamoDB to Voicehub when the user first calls the Skill after you have implemented Voicehub.


const LaunchRequestHandler = {
	canHandle(handlerInput) {
		return handlerInput.requestEnvelope.request.type === 'LaunchRequest';
	},
	async handle(handlerInput) {
		const { attributesManager } = handlerInput;

		/* Retrieve existing Properties */
		const attributes = await attributesManager.getPersistentAttributes() || {};
		/* Find or Create a new User */
		const user = await voicehub.user(handlerInput).findOrCreate();

		/* Copy over existing Properties if the user is new on Voicehub */
		if (user.isNew && Object.keys(attributes).length > 0) {
			user.set(attributes);
			await user.save();
		}
		// the rest of your code ...
	},
}

Node.js SDK

We provide a Node.js for you to integrate into your voice app. Both Alexa Skills and Google Actions are supported, thus you can use our SDK in combination with alexa-skills-kit and dialogflow-fulfillment-nodejs. In general, you can use the SDK in combination with any Node.js environment, though some features might only be added in the future.

Install

Our SDK is available via npm. Use the following command to install and save it to your projects dependencies.

npm i -S @voicehub/voicehub

Initalize & Authenticate
At the very top of your code, require the module and provide your API username (which is your Voicehub App ID) and your API key:
  • APP_ID: The ID of your App on Voicehub, can be found here.
  • API_KEY: An API Key from your Voicehub Account, can be found here.
const voicehub = require('@voicehub/voicehub')('APP_ID', 'API_KEY');
The SDK is open source! If you have any ideas, requests or issues, don't hesitate and check out the Github repository. We also provide samples for an easy start:

Retrieve Content

Using the SDKs methods, you can easily retrieve content in form of posts created on Voicehub from within your voice app code.

Manage Users

You can fully manage the users of your voice app with Voicehub. You can store any kind of information about your user within Voicehub, and retrieve it when you need need it in your code. The SDK provides an easy interface to interact with the API.

Analytics

Voicehub is not only a content management platform for the content of you voice app, it also has extensive analytics features. Using the SDK, you can let Voicehub analyze many metrics about your voice app with just a few lines of code.

Reference

voicehub('app_id': string, 'api_key': string): Voicehub

Construct a Voicehub Instance

Construct a Voicehub Instance
Parameter Type Example Description
app_id

string

5ce68ed502ef3e46342d6712 The ID of your App in Voicehub.
api_key

string

058fbd3a-b590-4997-9c38-ee01a8256a6f Any one of your API Keys.

Content Management


.setLocale('locale': string | object | null): void

Set the Locale for the Instance

Parameter Type Example Description
locale

string | object | null

en-US Use a BCP-47 tag as string or handlerInput/agent object to set a locale for posts to be retrieved. When set, you can call post.fieldName and get the contents directly, instead of calling post.body.fieldName.content['en-US']. You can also set the locale to null to switch back to the "default behaviour".
.post('post_id': string): Post

Construct a Post Instance by _id

Parameter Type Example Description
post_id

string

5ce544e6dac9001d0s23cc5a Use this method to construct a post with its internal _id instead of its name. This makes you independent of the post name on Voicehub, which can be changed. You can however use the post name if you prefer, look at below .intent() method.
Properties of Post Instance
Property Description

_id

Returns internal _id for this post. Readonly.

locale

Returns the set locale for the user, or null.

app_id

Returns the Voicehub app_id for this user. Readonly.

model_id

Returns internal model_id of the model this post is based on. Readonly.

intent_id

Returns the internal intent_id this post is in. Readonly.

postIdentifier

Returns the post identifier used to construct this instance.

parameters

Returns parameters object used to construct this post instance, can be null.

body

Returns the post body containing the post fields.

has_draft

Returns true if there is draft content saved in this post, false otherwise.

createdAt

Returns UTC string of time of creation of this post. Readonly.

updatedAt

Returns UTC string of time of last update of this post. Readonly.
.withParameters(parameters: object): Post

Inject Parameters into Post

Parameter Type Example Description
parameter

object

{ age: 21 } If a post has a dynamic parameter in its content, you can provide a value for it here to have it resolved. You must provided all parameters that are used within the post, or none to retrieve it unresolved.
.get(): Promise<Post>

Retrieve Post from Voicehub

.intent('intent_id': string): Intent

Construct an Intent Instance by Name or _id

Parameter Type Example Description
intent_id

string

My Super Cool Intent The name of the intent on Voicehub or its internal _id, case-insensitive.
.post('post_id': string): Post

Construct a Post Instance by Name or _id

Parameter Type Example Description
post_id

string

My Cool Post Name Either the name of the post on Voicehub, or its internal _id.
Properties of Post Instance
Property Description

_id

Returns internal _id for this post. Readonly.

locale

Returns the set locale for the user, or null.

app_id

Returns the Voicehub app_id for this user. Readonly.

model_id

Returns internal model_id of the model this post is based on. Readonly.

intent_id

Returns the internal intent_id this post is in. Readonly.

postIdentifier

Returns the post identifier used to construct this instance.

intentIdentifier

Returns the intent identifier used to construct this instance.

parameters

Returns parameters object used to construct this post instance, can be null.

body

Returns the post body containing the post fields.

has_draft

Returns true if there is draft content saved in this post, false otherwise.

createdAt

Returns UTC string of time of creation of this post. Readonly.

updatedAt

Returns UTC string of time of last update of this post. Readonly.
.withParameters(parameters: object): Post

Inject Parameters into Post

Parameter Type Example Description
parameter

object

{ age: 21 } If a post has a dynamic parameter in its content, you can provide a value for it here to have it resolved. You must provided all parameters that are used within the post, or none to retrieve it unresolved.
.get(): Promise<Post>

Retrieve Post from Voicehub

.posts(): Array.<Object>

Get all Posts from Intent

Example Response:

[
{
	_id: "5ce5508b3a7776sega6a6727",
	name: "Returning User Welcome",
	app_id: "5ce544e6dac90234f13cc5a",
	model_id: "5ce54f4cf1dawdsd884128a",
	intent_id: "5ce544e6dac934sge13cc5d",
	has_draft: false,
	body: {
		speech: {
			type: "long_speech",
			content: {
				en-US: "<speak>Welcome to Voicehub</speak>"
			}
		},
		reprompt: {
			type: "long_speech",
			content: {
				en-US: "<speak>What can I do for you?</speak>"
			}
		}
	},
	createdAt: "2019-05-22T13:37:15.170Z",
	updatedAt: "2019-05-22T15:00:48.076Z"
},
]

User Management


.user('vendor_user_id': string | object): User

Construct a User

Parameter Type Examples Description
vendor_user_id

string | object

handlerInput

agent

'amzn1.ask.account.AESY7...'

Provide the SDK specific objects here to construct the user, which are 'handlerInput' for Alexa Skills and 'agent' for Google Actions. Alternatively, though not recommended, provide a string manually.
Example User Creation
/* Alexa */
const user = await voicehub.user(handlerInput).findOrCreate();
/* Dialogflow */
const user = await voicehub.user(agent).findOrCreate();
Properties of User Instance
Property Description

_id

Returns internal _id for this user. Readonly.

locale

Returns the set locale for the user. Readonly.

isNew

Returns true if user was just created (after .findOrCreate()), false otherwise. Readonly.

properties

Returns the set (custom) properties for this user. Can be set to null to override stored information.

app_id

Returns the Voicehub app_id for this user. Readonly.

vendor_user_id

Returns the vendor_user_id the user was created with. Readonly.

createdAt

Returns UTC string of time of creation of this user. Readonly.

updatedAt

Returns UTC string of time of last update of this user. Readonly.
User Methods
.findOrCreate(): Promise<User>

Find or Create User on Voicehub

.set(parameters: object): User

Set Object of Attributes for User

Parameter Type Example Description
parameters

object

{ age: 21 } Set a whole object of attributes for a user with this method. Don't forget to call user.save() afterwards!
.save(): Promise<User> | null

Save User to Voicehub

.get(): Promise<User> | null

Retrieve User from Voicehub

Analytics


.actionInterceptor(agent: object): void

Log Google Action Interactions

Parameter Type Description
agent

object

To use Voicehubs analytics features, you need to connect your Google Action with Voicehub using this method.
.interactionInterceptor(handlerInput: object): void

Log Alexa Skill Interactions

Parameter Type Description
handlerInput

object

To use Voicehubs analytics features, you need to connect your Alexa Skill with Voicehub using this method.

Contact and Support

Our goal is to assist you in creating great voice-first experiences by using Voicehub and utilizing our tools. If you have any questions, please reach out to us. We are active on Spectrum, our community hub, where you can ask your questions not only to us, but also to other Voicehub users. You can also write us a mail to info@voicehub.io.