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 simplyJSON 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.

Viewing Custom Commands from the Client Details Page.

Click the Enable Custom Commands button. Under the hood, this will add two domains to your client: Stored Always Match, and Stored Page Match. These domains assist with recognizing custom commands.

After enabling, you will be guided through a flow where you can create and test your first custom command.

The Guided Walkthrough shows you a pre-filled Custom Command creation form that you can edit.

When creating a new custom command, you can enter several fields. To make it easier for you, we’ve included some pre-filled content, but we’ll be replacing them.

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. It’s for your own record-keeping. Type in any string you want.

After updating the form, it should look like this.

Click Save.

Testing out your Custom Command

Now, you can test the command that was just created against the live Houndify API. Click on the mic and saying “go to the next picture”.

You can test your newly created custom command against the Houndify API.

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 Global Commands Page.

Your first custom command is now saved under the Global Commands Page.

We won’t dive into Pages here, but you can read more about Global Commands and Pages on 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.

Viewing Tests

All of your test phrases across all of your created commands are visible in the Test Phrases widget. It will let you know if any of your tests are not passing.

The Test Phrases Widget lets you know the status of all your test phrases across all of your custom commands.

Test Commands with the API

You can always test your commands against the Houndify API by clicking on the Test button. All of your Test Phrases are also available here.

The Try API Widget lets you send requests to the API using your Test Phrases.

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.

One clap, two clap, three clap, forty?

By clapping more or less, you can signal to us which stories really stand out.