This API is compatible with Homey version 1.2.0 and up

Your App can respond to a user's spoken phrases. It is one of Homey's essential interfaces, so you should give this a lot of care.

If you do want to use speech, Homey has a system to help you specify which user phrases are intended for your App. Picking the right App to process the user phrase is a two-step process. First, an event is triggered to candidate Apps. This gives Apps a chance to check if they can process the user phrase. The App with the highest score that can process the user phrase then gets another event emitted to execute the speech command.

Regarding devices, if you are using a Device Class, those devices will automatically respond to built in speech commands. So if you are making an App which adds support for, say, a light, speech commands such as lights on are managed by Homey. You only need to add speech for any custom Capabilities you may have added.

Listening for speech

You will need two pieces of code in your App. The first one is to do a quick check if your App can process this user phrase:


const Homey = require('homey');

// this events is called when your app is a possible candidate for received speech
Homey.ManagerSpeechInput.on('speechEval', function( speech, callback ) {
    let match = speech.matches.importantProperty.length > 3;
    callback( null, match );

The callback takes (err, result). If your App can process the user phrase, fire the callback with some truthy value as result. If your App cannot process the user phrase, callback with an error or a falsy result. If the callback was not called after 1000ms, the response is assumed (null, false).

When your App turns out to be the best App to process the user phrase, Homey emits the speechMatch event. You will need this piece of code to execute the user phrase:


const Homey = require('homey');

Homey.ManagerSpeechInput.on('speechMatch', function( speech, onSpeechEvalData ) {
    // onSpeechData is whatever you returned in the onSpeech callback
    // process and execute the user phrase here

These events are fired when your App has defined the speech object in its /app.json.


    "id": "com.athom.hello",
    "speech": {
        "en": {
            "element": {
                "actionWords": {
                    "type": "regex",
                    "value": "(look\\s?up|find|search(\\sfor)?|tell(\\sme|\\sus)?\\sabout)"
                "wikipedia": {
                    "type": "regex",
                    "value": "((on\\s)?wikipedia|wiki)"
                "query": {
                    "type": "regex",
                    "value": "[\\s\\S]+"
            "group": {
                "main": {
                    "set": "(actionWords) && wikipedia && query",
                    "ordered": false,
                    "allowDisconnect": true,
                    "capturingGroup": true
    "speechExamples": {
        "en": [ "Tell me about domotica on Wikipedia.", "Look up domotica on Wikipedia." ],
        "nl": [ "Vertel me over domotica op Wikipedia." ]

The speech information is created by combining different "building blocks". These building blocks are called Elements and they are used in Groups. The combination of Elements and Groups lets you specify the different ways someone can talk to your App without having to spell out every different way a command can be worded.

Visit http://yourhomeyip/manager/speech-input/ to manually enter speech, and http://yourhomeyip/manager/speech-output/ to make Homey talk while testing your App.

Asking questions

After receiving a speechMatch event, your App can ask a question and give the user the possibility to respond.


Homey.ManagerSpeechInput.on('speechMatch', function( speech, onSpeechEvalData ) {

    speech.ask('What is your name?', function( err, result ) {
        if( err ) return Homey.error(err);
        // result is the transcript of the user, in this case it might be `Mike`

        speech.say( Homey.__('hello', {name: result}) ) );


Speech sessions

Speech can originate from various locations: Homey itself, a mobile phone, a chat client etc.

In almost all cases, your App should use the methods speech.say(), speech.ask() and speech.confirm() after a speech event has been received on the Speech Input Manager. By using these methods, the speech session (where it came from) is preserved, so Homey answers to the correct session. If your App uses ManagerSpeechOutput.say() instead of speech.say(), Homey will always talk back using its internal speaker!

Human Interface Guidelines

Speech interfaces are relatively new for users, so it is important to get them right. Please follow the guidelines listed below for a better user experience of your App.

  • In almost all cases, respond with speech when the user asks something. Additionally, respond visually if it makes sense as well (e.g. OK Homey, red lights), a red LED Ring pulse).
  • Expect users to talk to Homey in full sentences (OK Homey, what is the weather tomorrow?), but also with short commands (OK Homey, weather tomorrow).
  • Give meaningful confirmations by repeating what Homey will do (e.g. "Turning lights to red").


The speech information is specified separately for each language. Speech information for the English language is required. The currently supported languages are en (English) and nl (Dutch). Elements are required to be listed in each language you want your App to work in. If you do not include a Group property for a language other than English, the English group structure will also be used for that language.

Child Topics