How to add Custom Commands to your Houndify Client

Follow this step-by-step guide to add support for custom phrases to your Houndify Client.

When building applications using Houndify, a common use case is to support custom queries and phrases. For example, imagine you are building a Smart Digital Photo Frame.

You may want to support voice commands such as:

• “Go to the next picture”, or “Next”.
• “Go to the previous picture”, or “Go back”.

For these use cases, you can leverage the Houndify’s Custom Commands Feature. That’s what we’ll be covering in this tutorial.

What are Custom Commands?

At their core, Custom Commands are simply JSON objects that your client provides to the Houndify server.

A Custom Command JSON object consists of two primary parts:

1. Expression: This is the phrase or query that you want your client to understand.
2. Result: If the above expression is matched by Houndify, a JSON result that you specify is returned to your client. You can then check this JSON to see what expression was matched.

These JSON objects can be managed using Houndify’s Custom Command Web Interface.

Writing your first Custom Command

For this section of the tutorial, we’ll assume that you already have a Houndify account. If you don’t, head over to houndify.com and create one for free.

Let’s start with the example mentioned above: we will create a client that can understand the following expressions:

• “Go to the next picture”, or “Next”. If someone says this, our client will understand it and return a JSON saying {action: “NEXT”}
• “Go to the previous picture”, or “Previous”. If someone says this, our client will understand and return a JSON saying {action: “PREVIOUS”}.

So those are our expressions and results. Let’s get started.

Click on a client from your Dashboard that you would like to enable Custom Commands for, or create a new client.

In the Client Details view, go to the Custom Commands section. It will look like the image below.

Enabling Custom Commands

Click the Enable Custom Commands button. Under the hood, this will be the Stored Page Match domain. This domain assists in recognizing custom commands.

After enabling, you can create your first page. Pages allow you to organize custom commands into logical groups. Click the New Page button to enter a name for the page.

For our photo album we type:

Photo Album

for the page name and click Add Page

After creating a page you will be guided through a flow to create and test your first custom command.

After updating the form, it should look like this.

When creating a new custom command, you can enter several fields.

Expression: This is the expression that you want to match. Change the expression to:

("next" | "go" . "to" . ["the"] . "next" . "picture")

Result: This is the JSON that will be returned if the expression is matched. Change the result to:

{"action": "NEXT"}

Response: This is a string that will be returned if the expression is matched. Change the response to:

Going to the next picture

Test Phrases: You can enter some test phrases that should or should not be matched by your expression. This helps you ensure that your expression is working correctly.

Update the test phrases to the ones listed below. They should all pass.

Should Match:      Next
Should Match:      Go to the next picture
Should Match:      Go to next picture
Should Not Match:  Go to previous picture

Comment: This is a string that helps you identify this expression later. Choose something that is meaningful to you.

Click Save and Test followed by Close

Testing out your Custom Command

Now, you can test the command that was just created against the live Houndify API. Click on the Test with the API button to the get to the test page. Click the mic and say “go to the next picture”.

Testing your custom command

You’ll notice that the expression was recognized, and the Result JSON and Response was returned.

That’s it! We just wrote a Custom Command for the following 3 phrases:

• “Next.”
• “Go to next picture.”
• “Go to the next picture.”

Click Done to close the modal. You’ll notice that the Custom Command that you just created was added to the Custom Commands List within the Page you made.

We won’t dive into the Default Matching Behavior settings. For more information check out the Houndify Developer Guide.

Next Steps

Creating More Commands

Now that you have created your first command, you can create another one to manage the second expression:

• “Go to the previous picture”, or “Go back”.

We’ll leave this exercise up to you. Clicking on the New Command button will bring up the familiar modal window.

Editing Existing Commands

You can edit existing commands by clicking on the Pencil Icon in the Commands List.

Ready to code?

Once you are comfortable with your custom command expressions on the web, we recommend that you download one of our SDKs.

You can also read more about Custom Commands on the Houndify Developer Guide.

Head on over to Houndify.com to create a free developer account, and start building applications that understand natural language.