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:
- Expression: This is the phrase or query that you want your client to understand.
- 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
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
- “Go to the previous picture”, or “Previous”. If someone says this, our client will understand and return a JSON saying
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.
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.
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:
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.
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’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:
- “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.
We won’t dive into Pages here, but you can read more about Global Commands and Pages on the Houndify Developer Guide.
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.
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.
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.
Head on over to Houndify.com to create a free developer account, and start building applications that understand natural language.