Ask Alexa

The Unofficial SmartThings Blog
Revision as of 11:03, 30 September 2020 by MichaelStruck (talk | contribs) (Roadmap)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search

Ask Alexa is an add-in to the SmartThings mobile application that allows you to control a broad array of devices with your Amazon Alexa Enabled Devices. When installed along with the proper services at AWS (Amazon Web Services), a simple voice command allows you to control your devices along with querying their status. Simply "Ask" Alexa to do something within your SmartThings environment and she will respond!

Ask Alexa can replace the basic integration between SmartThings and Alexa. In the default SmartThings integration, you may only control switches and thermostats and there is limited feedback to ask the status of the devices. Ask Alexa improves this integration by not only expanding the devices you can control with your voice, but you can now get real-time feedback on inside temperatures, door, switch, dimmer status, etc, and control modes, Smart Home Monitoring security status, run routines and set up complex macro-like events using natural speech. You can even interface other SmartThings SmartApps into Ask Alexa by using the message queue function and access another popular community-written app, WebCoRE, directly from Ask Alexa (and in turn, Ask Alexa macros can be referenced within the WebCoRE application itself).

No matter how you want to address your home, from a more "Star Trek" experience ("<Computer, tell studio to turn the lights on">) to natural language (<"Alexa, tell the house I am cold">), Ask Alexa is the go-to app for SmartThings/Alexa integration.





Category: My Apps

Author:Michael Struck --MichaelStruck (talk) 00:01, 1 January 2016 (EST)

ST Community handle:

Code contributions: Keith DeLong, Barry Burke, foxxyben & M3Rocket (utterances), Jimxenus/larry-fuqua (misspellings/logic issues in the GUI), jhamstead and Yves Racine for Ecobee code

Documentation contributions: Keith DeLong, Jason Headley, Belgarion, Barry Burke, Andrea Bianco, Yves Racine, Todd M(@Pantheon)

Latest Versions

The latest version of each of the applications listed in this document (as of 1/14/19)
Ask Alexa Code Area Used Version Location
SmartApp Code SmartThings IDE 2.3.9h
Node.js Lambda code for (manual install only) 1.3.1a
Ask Alexa Extensions Area Used Version Location
Message Queue Code [1] SmartThings IDE 1.0.8
Rooms/Groups Code [2] SmartThings IDE 1.0.4b
Schedules Code [3] SmartThings IDE 1.0.4a
Voice Report Code [4] SmartThings IDE 1.0.9
Weather Report Code [5] SmartThings IDE 1.0.8

Compatibility With Other SmartApps

Ask Alexa isn't limited to just the standard devices that come with SmartThings. It can also work directly with other SmartApps and even some custom Device Type Handlers. The following is the current list of compatible SmartApps/DTHs...Items with (2.0) designation already or will support the new message queue structure (see Ask_Alexa_-_Message_Queues):

SmartApp/Custom Device Type Supported Features Author
NST Manager Message queue (2.0) and thermostat reports Anthony Santilli
WebCoRE Message queue (2.0) Adrian Caramaliu
My Ecobee Device & Service Manager (MyEcobeeInit) Message queue (2.0) - Comfort & Energy Saving tips for your Ecobee device, ecobee Alerts, exception events and tstat reports Yves Racine
Zoned Heating/Cooling Solutions (ecobeeSetZoneWithSchedule, ScheduleRoomTempControl, ScheduleTstatZones) Message queue (2.0) for reporting heating/cooling zoned scheduling events Yves Racine
Device Monitor Message queue (2.0) Eric Maycock
MonitorAutomaticCar Message Queue (2.0) for reporting hard acceleration/brake/ignition off/on and other Automatic events Yves Racine
OSRAM Lighting Controls-DTH [6] Loop/Pulse gkl-sf
Foobot Air Quality Monitor-DTH[7] CO2/Particles/VOCs/Temperature/Humidity Michael Struck/Adam V
Big Talker Message Queue (2.0) Brian Lowrance
Lock Manager Message Queue (2.0) Erik Thayer
RemindR Message Queue (2.0) Bobby Dobrescu
Smart GCal Control Message Queue (2.0) Anthony Pastor (infofiend)
Sports Notifications Message Queue (2.0) Eric Luttmann
Spruce Status Message Queue (2.0) Barry Burke
Open Source Ecobee Thermostat, Sensors and Companion SmartApps Message Queue 2.0 for Ecobee Alerts and Reminders Barry Burke
My Ecobee stats generation Smartapps Message Queue (2.0) for reporting ecobee daily/weekly/monthly runtime (HomeIQ) stats Yves Racine
MyNeurio & MyNeurioAppliance Service Managers Message Queue (2.0) for reporting exception events and summary Energy Consumption & Generation reports (Daily, Weekly, Monthly) Yves Racine
MyAutomatic Service Manager Message Queue (2.0) for reporting exception events and Driving Summary Reports (Daily, Weekly, Monthly) Yves Racine
MonitorAndSetEcobeeHumidity Message Queue (2.0) for humidity control notifications - using HRV/ERV/Humidifier/Dehumidifier devices connected to your ecobee Yves Racine
MyFlair Devices (Puck, Vent, HvacUnit) & Service Manager Message Queue (2.0) for reporting event summary reports (Daily, Weekly) & exceptions Yves Racine
MyNextManager & Devices (Tstat, Alarm, Cam) Message Queue (2.0) for reporting event summary reports (Daily, Weekly) & exceptions Yves Racine
Room Occupancy Control over the occupancy of a room using a custom DTH, Message Queue (2.0) Bangali
GE Motion Switch/Dimmer Verbal control over the operating mode of the switch (models 26933 and 26931) Michael Struck

Open Source License/Trademarks

Licensed under the Apache License, Version 2.0 (the "License"); you may not use Ask Alexa code except in compliance with the License. You may obtain a copy of the License at:

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

All product and company names are trademarks™ or registered® trademarks of their respective holders. Use of them does not imply any affiliation with or endorsement by them.


The following are the basic requirements to use Ask Alexa:

  • A mobile device running the SmartThings mobile application
  • An Amazon Alexa Enabled Device (it is not required the device be integrated with SmartThings, but doing so won't interfere with Ask Alexa)
  • Devices (Switches, lighting, thermostats, etc) that are operational within the SmartThings environment. To help Alexa understand your devices, they should each be uniquely named in your account.
  • An AWS Lambda and developer account
    • For the developer account, please ensure you create the account under the same account you used for your Amazon Alexa Enabled Device setup. See the steps to create the account here.
    • For the AWS/Lambda account (to host your code), follow the instructions here. Please note that you MAY need to provide a credit card for the setup. Be sure to read the pricing structure for AWS Lambda space here.

Privacy Statement

Ask Alexa leverages an external web hosting service to automate some of the setup and operation of the SmartApp. To ensure complete transparency, you may read the privacy statement here: [8]


  • The instructions presented here are for US installations only. While many of the concepts are universal, all screen shots and languages assume US/English installations. If you find some slight variation are needed in these instructions please update the wiki or contact the author of this application.


Throughout this document there will be some specific terms relating to the SmartThings and Amazon development environments.

SmartThings/Ask Alexa/General Definitions

  • SmartApp: Add-in to the SmartThings mobile application that allows for functionality outside of what is provided by default. These SmartApps are not stand alone programs, but only operate within the SmartThings mobile application. SmartApps are open source and written in a form of the Java programming language called “groovy”.
  • Parent/Child SmartApp: A code structure within the SmartThings development environment where a single instance of a parent SmartApp can have multiple child SmartApps associated with it, allowing the single SmartApp to have multiple functions. Ask Alexa uses this structure for its extensions; there can only be one instance of the Ask Alexa SmartApp and each extension created within the parent SmartApp is actually an instance of the child SmartApp. This structure cuts down on repeated code within a single SmartApp.
  • Virtual Switch: A device within the SmartThings environment that functions like a regular switch (think of a button or a light switch). However, the device is “virtual” and does not exist as a physical device. Used mostly with Alexa Helper. However, you can activate virtual switches using Ask Alexa as well.
  • Alias: In the context of Ask Alexa, this is a name that is used as a place holder (or alias) for another device. This allows to have two devices named the same thing within your SmartThings app, but allows you to address them differently in Ask Alexa.
  • IDE: Abbreviation for “Integrated Development Environment”. In the context of the SmartThings environment, this is the web site located at or (depending on your country) that allows for advanced functionality within the SmartThings environment. This allows you to set up custom devices and applications that appear within your SmartThings mobile application.
  • DTH: Device Type Handlers. This is code that is usually community written and allows third-party devices to operate in the SmartThings environment. A good example of this is the Nest Thermostat.
  • GitHub: A web-based repository that allows for distribution revision control and source code management functionality.
  • OAuth: Provides client applications a secure method for accessing resources on behalf of the resource owner. Within the context of SmartThings, certain custom applications that allow for remote access (such as remotely turning on or off a light) will require additional authentication. As the owner of the resource, you can authorize remote access to an application by enabling OAuth.
  • Access Token: A security identity that is linked to OAuth and in the context of SmartThings allows for remote control of a locations devices.
  • URL: Uniform Resource Locator, or basically the address of a web site or online resource, such as
  • REST: REpresentational State Transfer is an architectural style, and an approach to communications that is often used in the development of Web services. In SmartThings, it is how external applications, such as Amazon's services, can interact the devices in your account, using the OAuth and Access Token as 'keys' to securely access these devices.
  • Text Field Variables: In the context of Ask Alexa, these are variables that can be used in any text areas of the macros to give you 'short cuts' to commonly used text. Typically, they start and end with a percent sign, like %temp%. See Ask_Alexa#Text_Field_Variables for the variables currently available.
  • WebCoRE: Web Community's own Rule Engine. Another SmartThings community developed application that defines 'pistons' to perform complex, decision-based automation. One of these events could be a trigger from Ask Alexa. More information can be found here:

Amazon/Alexa Development Definitions

  • AWS: Amazon Web Services is a collection of cloud computing services that make up the on-demand computing platform offered by
  • Lambda: An AWS service. Lambda lets you run code without provisioning or managing servers. With Lambda, you can run code for virtually any type of application or back-end service - all with zero administration.
  • A.S.K.: The Alexa Skills Kit is a collection of self-service APIs, tools, documentation and code samples that make it fast and easy for you to add skills to Alexa.
  • Invocation Name: This is the name you will "invoke" to communicate with the Alexa Enabled Devices, which in turn communicates with SmartThings and Ask Alexa. By default, the invocation name using in Ask Alexa is "smart things"; however, the invocation name can also be words like "home", or "house" to make command syntax smoother. You may even set up multiple skills, each with the name of a room, and have personalized responses for each room. For example, you could say <"Alexa, tell the kitchen to turn off the lights"> and affect the Kitchen, or <"Alexa, turn the lights off in the bedroom"> and only have the lights in the bedroom react.
  • Intents: An intent represents an action that fulfills a user’s spoken request. Intents can optionally have arguments called slots.
  • Custom Slots: A custom slot type is used for items that are not covered by Amazon’s built-in set of types and is recommended for most use cases where a slot value is one of a set of possible values. The values for the custom slots are generated for you via the Settings page. You will simply copy the provided data and paste it into the Amazon Developer Site.
  • Utterances: A structured text file that connects the intents to likely spoken phrases and containing as many representative phrases as possible.
  • JSON: is an abbreviation for JavaScript Object Notation is a lightweight data-interchange format that is easy for humans to read and write and easy for machines to parse and generate. The Amazon ASK Development area uses JSON for sending input to and from the Alexa Enabled Devices. The basic structure of JSON looks like this:
      "intent": "DeviceOperation",
      "slots": [
          "name" : "Operator",
          "type" : "LIST_OF_OPERATORS"

How Ask Alexa Works

Unlike most SmartThings SmartApps, Ask Alexa works in concert with the external Amazon developer site, including the Lambda web service. However, the "heavy lifting" of determining the condition of your house, generating reports, and most of the feedback spoken by the Alexa Enabled Devices is actually produced by your SmartThings account, NOT the Amazon cloud services. See the diagram below for a bit more detail on this.


Thanks to Keith DeLong for the above diagram.

The user will query their Amazon device, and the Amazon "skill" simply looks for the nouns and verbs (keywords) of your speech and then send those key words to your SmartThings account. The Ask Alexa SmartApp processes this information, does its actions, and sends Amazon the text response to process through its text-to-speech function. Basically, the Alexa Enabled Device is not turning on your devices...your Ask Alexa SmartApp is doing the work.

Set up of your Alexa Enabled Devices

Setup of your Amazon Alexa Enabled Devices with SmartThings native functionality is NOT required to use Ask Alexa. Ask Alexa operates independently of the integration. However, to have a backup method of controlling your environment, or to use apps like Alexa Helper, you will need to follow the steps below. Please refer to your Amazon Echo documentation, use the Amazon Echo mobile app, or visit for more information.

  • Configure your device on your home’s Wifi and ensured that it is functional
  • Configure the device to work with your SmartThings Devices [[9]] (via the Amazon Echo application on your mobile phone or Setup within the Amazon Echo app is under Settings and Connected Home)
  • Once SmartThings is properly configured, go into the Amazon Echo SmartApp within SmartThings (See image to the right) and click on the switches you intend to use. These can be real switches/dimmers, virtual switches or momentary button tiles
  • Click <<Done>>, then say to your Alexa Enabled Device <"Alexa, discover new devices">
  • Within the Amazon Echo Application (NOT the SmartThings app), or, you should now see the switches you have "Discovered"
  • If you later add switches to SmartThings, you will need to add them to Amazon Echo Smart App within SmartThings, then "Discover" them

Setting up your Amazon Lambda and Developer Accounts

To use Ask Alexa you will need to create two "free" accounts at Amazon. While the full instructions on setting up these accounts is outside of the scope of this document, very clear instructions are published by Amazon themselves:

Developer Account

Lambda Account

Please note that these account are 'free' (see the information here[10]). Please be sure to ONLY sign up for the Lambda piece, and the 'basic' tier of service. You MAY be required to provide a credit card number, however, to open an account.


   While the Lambda account is listed as free, if you generate excessive 
   traffic from your account, Amazon WILL charge you. Fortunately, this 
   level of traffic would need to exceed 5 million hits per month to account
   for even $1.00. So, while the accounts are 'free' for general use, full 
   public distribution and use would definitely incur a fee if your volume 
   is high enough.

Ask Alexa (SmartThings Code) Installation

There are multiple methods to get Ask Alexa installed into the SmartThings environment. You can use the Community Installer, manually install the code from the links in GitHub, or use the IDE/GitHub integration within SmartThings.

Community Installer (Free Marketplace)

To install Ask Alexa via the Community Installer, please see here:

Simply find Ask Alexa in the list, and install ALL pieces of the application (including Extensions or 'child' applications). If you are upgrading, click the <<Update>> button.


Manual Installation

The code for the Ask Alexa SmartThings SmartApp is found on the GitHub site:

While on the GitHub site, find the Raw button and click it. This will bring up a non-formatted page with just the code present. Select all of the code (typically CTRL+A) and copy It (typically CTRL+C).



  • Once you are logged in, find the My SmartApps link on the top of the page. Clicking My SmartApps will allow you to produce a new SmartApp.


  • Find the button on this page labeled +New SmartApp and click it.


  • Since you already have the code in your computer’s clipboard, find the tab along the top section called From Code. In the area provided, paste (typically CTRL+V) the code you copied from GitHub. Click Create in the bottom left corner of the page.


  • This will bring up another page, with the code now formatted within the IDE. If the code was copied correctly, there are no other steps except to save and publish the code. In the upper right corner of the page, find and click Save. Now, click Publish (For Me), and you should receive a confirmation that the code has been published successfully.


OAuth Setup

Ask Alexa will need to be accessed by the Amazon servers in order to operate correctly. As such, OAuth is REQUIRED for this application.

To enable OAuth, first find and click the App Settings button in the upper right corner of the page.

From here, find the OAuth section toward the bottom of the page.


Clicking the OAuth link will reveal a button labeled Enable OAuth in Smart App. Click this button. The screen will change, giving you a unique code for your Client ID and Client Secret. These are the foundations of the security of your app and should be kept secret. You do not need to memorize or write down these codes; nor do you need to add any other information to this page. OAuth simply needs to be enabled for Ask Alexa to operate.


The final step is to press the Update button at the bottom left corner of the screen, or go back to your code by using the button in the upper-right region of the page, then Save, then Publish the SmartApp again.


Ask Alexa Extension Code Installation

Next, you will need to load up the child extension SmartApps. This code for these are located here. Installation is exactly the same for each one. Just repeat the steps below for each set of code.

The steps for installation are almost exactly the same as Ask_Alexa#Ask_Alexa_Code_Installation:

  • Copy the raw code from the GitHub link above
  • Go to the SmartThings IDE page and log in
  • Click the My SmartApps link
  • Click the +New SmartApp link
  • Click the From Code tab
  • Paste the GitHub code in the open area
  • Click Create from the bottom left corner
  • Save the code using the button in the upper right-hand corner of the page
  • There is no need to do any OAuth settings on extension code.
   Please Note:
   You DO NOT need to publish the extension code; however, there is no harm in doing so. 
   Simply be aware that if you publish it the extension will show up in the 
   SmartThings Marketplace. However, you should NOT install it from there...
   Ask Alexa will utilize this child code from the main (parent) application.

Advanced Installation

For advanced users who have their SmartThings IDE integrated with GitHub, the installation and maintaining of SmartThings SmartApp code becomes very simple. This manual will not go into detail about setting up your IDE with GitHub; those instructions can be found on the SmartThings web site [[11]]

   Please Note: 
   This process only applies to installing the SmartThings SmartApp. 
   This process DOES NOT update any of the code on the Amazon developer site; 
   you will need to follow the process Ask_Alexa#Building_The_Skill to 
   install or update your skill information.

Once you have integration, the four pieces of code you might need will be available to you to download and keep in sync with the latest versions.

  • First, find the Settings button at the top of your SmartThings IDE page (this will only appear after you integrate with GitHub)


  • Clicking this button will open the GitHub Repository Integration page. To find the Ask Alexa SmartApp code, enter the information as you see it below:
Owner Name Branch
MichaelStruck SmartThingsPublic Master


  • Close the GitHub Repository Integration page
  • Next, click the Update from Repo button at the upper-right corner of the IDE
  • On the right-hand column, scroll down to click the apps you want to install. These will typically be:

GitHub location of Apps/Extensions
SmartApp Location
Main Ask Alexa smartapps/michaelstruck/ask-alexa.src/ask-alexa.groovy
Message Queue Extension smartapps/michaelstruck/ask-alexa-message-queue.src/ask-alexa-message-queue.groovy
Rooms/Groups Extension smartapps/michaelstruck/ask-alexa-rooms-groups.src/ask-alexa-rooms-groups.groovy
Scheduler Extension smartapps/michaelstruck/ask-alexa-schedule.src/ask-alexa-schedule.groovy
Voice Report Extension smartapps/michaelstruck/ask-alexa-voice-report.src/ask-alexa-voice-report.groovy
Weather Report Extension smartapps/michaelstruck/ask-alexa-weather-report.src/ask-alexa-weather-report.groovy
   When adding code from the repo you have to add it in a 
   specific order or the IDE will generate an internal server error.  
   Add the main Smartapp (Ask Alexa) to your IDE first.  Then you can 
   add the extensions.
  • Click the Execute Update in the bottom-right corner of the screen. When done syncing, the new apps should now appear in your IDE. If they ever change color, that indicates a new version is available.

Ask Alexa SmartApp Installation

If you installed the code properly, you should find the Ask Alexa SmartApp located in the SmartThings Mobile Application under Market Place>>>SmartApps>>>+MyApps. If you have published any of the Ask Alexa extension you may see them in this list as well. DO NOT install those; just install the main Ask Alexa app. You may install extensions via the parent SmartApp.


After you install Ask Alexa, it is a good idea to set it up, and THEN do the Amazon setup pieces (Ask_Alexa#Developer_and_Lambda_Code_Installation). This will limit your need to go back and forth as the way you configure Ask Alexa determines how you set up the Amazon Developer's site.

Ask Alexa Interface

When you first open the SmartApp, you will be greeted with colorful icons where you can interface items with Alexa. Some of these items allow for control (i.e. switches, doors, locks, etc), and some will only provide their status (open/close sensors, water sensors). More devices are being integrated as the application matures. Some menu items (like the <<Device Aliases>>) may not appear in your interface until you activate the appropriate options in the <<Settings>> area (see Ask_Alexa#Allow_Device_Aliases)

It is recommended that you now add the devices you will want control of and status of to the interface before going on to the next steps of setting up the Developer/Lambda accounts. This will prevent your having to repeat these steps upon the completion of your installation.


Interface Items

Currently, you have the ability to interface switches (dimmers and colored lights), locks, temperature/humidity devices (including thermostats), open/close, presence, motion and water sensors, along with your SmartThings modes, Smart Home Monitor and Routines to your Alexa Enabled Devices. Please note that in addition to the devices to interface, if you have the <<Allow Device Aliases>> enabled in the <<Settings>> area, you will also see options to add devices that can have aliases associated with them.

  • Lighting/Switches-These devices are very straight forward; you can turn them on, off or toggle their state (<"Alexa, ask SmartThings toggle the Living Room">), change the level of a dimmer (<"Alexa, tell SmartThings to set the Dining Room to 50%">), or even change the color of a bulb (<"Alexa, ask SmartThings to set the Den to Blue">). In addition, you can ask the status of a device easily (<"Alexa, ask SmartThings the status of the Living Room">). For items like colored lights, two commands may be combined into one...For example <"Alexa, ask SmartThings to set the Den to Blue and to 50%">. Also on this page, if you choose colored lights, you will find the option to add a custom color as well under the <<Settings>><<Custom Color Setup>> (Ask_Alexa#Custom_Color_Setup). As is customary with dimming controls, only positive numbers between zero and 100 are accepted; any numbers exceeding this value will be normalized to the 0-100 range. Finally, you can use custom commands like maximum, increase, decrease, brighten, dim and low, medium and high to specify default behavior of dimmable switches.
   Please Note
   There are over 150 available colors to choose from in the latest version of Ask Alexa.
   A full list of colors would take minutes to recite; if you need to reference 
   these colored names, it is recommended you view the cheat sheet 
   (see Ask_Alexa#About_Ask_Alexa) or the FAQs (see: Ask_Alexa#Frequently_Asked_Questions_.28FAQs.29).
   The names of the colors come directly from SmartThings. Again, if one of these colors 
   do not meet your needs you can define your own custom color.
   For Temperature (Kelvin) lights, you have the option of choosing four settings, 
   "Soft White", "Warm White", "Cool White" and "Daylight White", setting the lights 
   to 2700K, 3500K, 4500K and 6700K degrees Kelvin, respectfully. These are the only 
   temperature setting available for these lights, which are typically white LED lights.
   You can change the default value of these 4 settings by going to <<Settings>>
   <<Default Command Values>>. See Ask_Alexa#Default_Command_Values
  • Doors/Windows/Locks-Another simple set of devices that can be addressed using natural language. A simple command such as <"Alexa, tell SmartThings to unlock the front door"> will unlock the door. To enhance security, you do have the option to set up a PIN to prevent these simple commands from allowing access to critical devices (see Ask_Alexa#Password_PIN). In addition, you can disable commands like "Open" Or "Unlock" for additional security. As with the switches, you can always query the status of device (<"Alexa, ask SmartThings about the Garage Door">). In this category are window shades, locks, doors, and open/closed sensors which are usually used for door or window open/close status.
  Important Notice Of Liability
  It can not be stressed enough that allowing your locks or doors to be controlled by
  this SmartApp lowers the security of your household. Anyone with knowledge of your 
  home setup (including your PIN) can open/close/lock/unlock these devices. The author 
  of this application accepts NO RESPONSIBILITY with intentional or unintentional  
  use (or misuse) of these features. Use SmartThings holistically; if you enable this
  feature ensure you are also properly monitoring/alerting on the devices as well.
  • Environmentals- Many SmartThings devices have temperature, humidity or even UV sensors built into them. As such, you may query the status of these devices to get their current readings. Also, you may set the set any SmartThings connected thermostat to a specific setpoint. Please note that many thermostats have both heating and cooling setpoints. As such, unless you have your thermostat set to just heating or just cooling, it is a good idea to ensure you are setting the proper setpoint. For example, if you thermostat is in auto mode, you could say <"Alexa, tell SmartThings to set the heat in the office to 65 degrees">. If your thermostat is in a specific mode (like heating), it is perfectly acceptable to just ask her to set the temperature setpoint...<"Alexa, tell SmartThings to set the office to 65 degrees">
   Please Note
   <<Environmentals>> is the area you are most likely to have the same device
   in multiple device categories. For example, you might have a humidity sensor that can
   also be added as a temperature sensor, or an air quality monitor that registers humidity.
   The program will not operate correctly if you choose the same device in multiple areas. 
   It should be noted, however, that if you turn on additional attributes within the <<Settings>>
   <<Device/Event Voice Setting>>menu that you can hear the additional parameters without choosing 
   the same device in two different categories.

When you select a thermostat you will be given the option to select some device specific commands. Various devices that work with SmartThings have powerful features or different command sets that don't comply with normal APIs provided by SmartThings. A good example of this is the Nest Thermostat; this device is not officially supported by SmartThings, but there are a few community-written device handlers that allows it to perform normal thermostat functions within your house. However, it also has other features that no other thermostats have; one of these features is the ability for the thermostat to act as a presence sensor, changing the way it behaves based on occupancy. The user may also set the "Home" and "Away" status manually, or through automation. If you are using Nest Manager, you can even expand on the generic Nest commands with custom reports (i.e. <"Alexa, ask SmartThings for Nest report">.

Another example is the Stelpro baseboard heating thermostat. This device is supported by SmartThings, but had different modes of operation besides heating and cooling; these are "Eco" and "Comfort" modes. Ecobee3 (Connect), as yet another example, allows for specific modes such as "Home", "Away", "Sleep", and "Resume Program" commands.

MyEcobee & MyNext Devices' comfort & energy saving tips

If you have a Ecobee or a Nest thermostat, you have the ability to use a community-developed device type handler, written by Yves Racine, to get you tips to operating your device (and your home) more efficiently. To access these tips, do the following:

  • Go to <<Settings>>
  • Choose <<Device Specific Commands>>
  • Choose <<Ecobee Specific Thermostat Modes>>
  • Choose <<MyEcobee Specific Tips>>

Or if you have My Next Tstat for the Nest Thermostat:

  • Choose <<MyNextTstat Specific Tips>>

Then, you can use the following commands with My Ecobee or My NextTstat Device(s):

Individual commands

  • Give Tip/Play Tip - This will play the tips available in memory, one at a time, for this device. The tips will increment to the next tip in memory until they have all been heard, at which point they will replay.
  • Repeat Tip - This will repeat the tip that was just played and will not increment the tip counter.

Batch commands (Advanced)

  • Get Tips[Level] - Without a number given, it will default to "Level 1" tips, which are the most general. To choose additional tip levels, say that level (i.e. <"Alexa, tell SmartThings to Get Tips, level 3, for Kitchen">. Please note that this will NOT play any tips, it just tells the device handler to load the tips for you into memory.
  • Reset Tips - This will reset the tips in memory. You must then say 'Get Tips' (with or without level) for the device to obtain more tips.

For more information on the My Ecobee's Get Tips, please see here:

For more information on the My Next Tstat's Get Tips, please see here:

  • Connected Speakers- If you connected speakers such as Sonos, Bose or Samsung with SmartThings, they can be controlled with Ask Alexa. Basic commands are supported, with plans to implement other features in the future. Simple say, <"Alexa, tell SmartThings to play Bedroom Speaker"> and the device will come on. You can also pause, mute, and skip tracks. You can also give a volume command between 0-100. Like the dimmers, you can also "increase" and "decrease" the volume based on the settings you define in the <<Settings>> area.
   The Sonos integration within SmartThings is currently in listed as a "Labs" .
   release. This means certain functionality is subject to change or may not work as
   expected. This includes re-playing music from a saved list.
  • Other Sensors-You may have other sensors around your house that you would also like to report on. Currently, acceleration, water, presence, occupancy and motion sensors are available. With the water sensors, you get a status reading of either wet or dry. Presence and motion/acceleration sensors behave in a similar fashion, with one state (present or motion) or another. Similarly, using a custom Device Type Handler, you can also check the status or change the occupancy of a room. In addition, as most of these types of sensors also have temperature readings available, if you have the other attributes configured to play, the voice reading will include this as well. Finally, if the sensor is a battery operated device, the battery reading will play if below the designated threshold (Set in <<Settings>>). Typically, sensors are read-only. However, with version 2.2.2, you may use the concept of a 'virtual' or simulated presence sensor so that those without physical presence devices can be accounted for and automations can run based on their presence. Users simply 'check in' or 'check out' with Alexa when entering a location.Physical presence sensors will not work with these additional commands. You will need to create a simulated presence sensor. The instructions for installation of this virtual device is here: Virtual_Presence_Sensor.
  • Modes/Routines/SHM - Unlike the native SmartThings integration, Ask Alexa will allow you to query and/or change the modes or Smart Home Monitor status, in addition to running a specific routine. When speaking to Alexa, ensure you specify what you want to do: <"Alexa, ask SmartThings to run Good Morning Routine"> or <"Alexa, ask SmartThings the current Security status">. Be sure your mode or routine names also are unique among your SHM settings as well (i.e. Stay, Arm, etc.). If you have unique names to your routines and modes, you may shorten your commands to <"Alexa, tell SmartThings Good Morning">, assuming you have a "Good Morning" routine. Finally, you have the ability to require a PIN number to activate the modes/routines or change the Smart Home Monitor settings. This option will appear when you have the PIN enabled in the <<Settings>> area (see: Ask_Alexa#Password_PIN)
   Please Note
   For the Smart Home Monitor (SHM) functions, if you do not choose ANY states
   this will effectively release the 'reserved' words of "security", "smart home" and 
   SHM. This is useful if you have switches set up with those same words. For example,
   if you use the popular app "Smart Alarm" you can now have a virtual switch called 
  • Device Aliases - While it is recommended that you have unique names for each of your devices within your SmartThings environment, this is sometimes not possible or practical. However, you can't address devices that appear multiple times with the same name (i.e. the name "Living Room" that is both a lamp device and a motion sensor). To solve this, Ask Alexa allows you to set up aliases to allow you to access all the devices within your environment without having to rename your devices within the main SmartThings app. You must turn this function on in the <<Setting>> menu item and then select the devices you wish to create aliases for in each of the device categories above. Once you do this, you will see the <<Device Alias>> selection appear. Using the example above, you could keep controlling the living room lamp with just with the name "Living Room" and then create an alias for the living room motion sensor. Once set up, the alias name behaves exactly like any other devices, picking up parameters unique to the device type. Another good example is to shorten a device name so it is easier to address. For example, if you have a long name for your speaker (i.e. "Master Bedroom Sonos") you could create an alias simply called "speaker" to address that device (see figure below).


   Alias Usage Limitations/Notes
   * Aliases are one-to-one associations; to control groups of devices using a single name you 
   will need to create a room/group (see Ask_Alexa_Rooms/Groups).
   * Alias names must still be unique within the Ask Alexa app. This means the name should
   not be the same as any other device (or alias) or routine, modes or voice macros
   * When creating and deleting alias names, be sure to use the interface buttons provided on 
   the page and not the SmartThings "Done","Save" or "<" buttons. Using these may give you undesired results.
   * Speaking of interface, due to a limitation of the SmartThings GUI, when you create your first
   alias that names will 'stick' in the interface input areas, giving you an error if you do not change 
   it and simply press ADD again (as the alias name will be one that you just created). Be sure all of your 
   alias names are unique and that you change the interface when you add or delete an alias.



On the main Ask Alexa page, scroll down to the area labeled <<Extensions>>. Extensions can be thought of as 'mini' applications that expand the functionality of Ask Alexa. Currently, there are multiple extensions available: Macros (which are built in), Message Queues, rooms/groups, voice/weather reports and scheduling. Additional extensions coming soon.

   When naming your extensions (be it Message Queues, rooms, voice reports or Macro names or aliases),  
   ensure your names are unique not only within the context of the other extensions, but 
   within the parent app itself. That means an extension should not share the same name with
   devices, aliases, modes, or routines within the parent app. Taking this precaution will 
   eliminate confusion when addressing the Alexa Enabled Devices with commands.


For information about each extension, including setup instructions, please click on the appropriate link below:


Back on the main (parent) interface you will find the <<Settings>> area. This page is separated into four sections that allow you to customize your Ask Alexa experience. This includes what the Alexa device will say when you ask for a status of SmartThings devices, whether or not you need a password for security related items (like doors, locks, Smart Home Monitor settings, etc), and the default values used to set up and operate the SmartApp for your environment.

Setup Ask Alexa

The very top menu item is where you want to go for all things related to setting up Ask Alexa. This includes defining the Skill Invocation name, getting the setup variables for the Amazon AWS and Developer's sites, and displaying the command 'cheat sheet'.


Skill Invocation Name

At the top of the page you will set up a specific invocation name for the skill name. Throughout this document the assumption is that you use "Smart Things" (two separate words) as this name; however, it can be anything. If you do change it within Amazon developer web site, you SHOULD change it here to match.

Setup Variables

The voice system of the Amazon Alexa Enabled Devices is very programmable. Almost any device you have in your system can be addressed by name. However, the Alexa Enabled Devices do not know these names by default; you must input them into the Amazon developer site as custom slots (Ask_Alexa#Custom_Slot_Information). While this can be a tedious task, Ask Alexa reduces the steps by evaluating the devices you have chosen to interface and generate an HTML setup page, allowing you to copy and paste the information directly to the Amazon Developer site.

When you tap the <<Setup Variables Link>> you will be presented in your SmartThings Live Logging with a web page URL. Copy this link to a computer (desktop) browser and you will then be given a page with the various variables you will need to operate Ask Alexa properly.


Any time you add or remove devices, modes, routines, or reports to your Ask Alexa SmartApp, it is best practice to put the new information into the custom slots so Alexa recognizes the new commands.

   Please note
   If you find your IDE Live Logging is not presenting the data properly, the page presented
   on your mobile device gives you the address you need on your desktop browser to continue
   the setup process. Simply copy that address to an e-mail (or other method) the can be 
   sent to your desktop environment. Of course, the Live Logging method is the preferred 
   method of obtaining this setup URL.
Cheat Sheet

At the bottom of the setup page you will find a section to produce a list, or "cheat sheet" of all of the devices (and aliases) that are set up within Ask Alexa.

While tapping this section produces the list on your mobile device, you may want to render this on a computer browser to allow you to print this page out. To do this, have your IDE Live Logging active. When you open the page you will see a link. This is similar to the link you acquire the setup variables from (See Ask Alexa#Setup Variables)


Once you have the link, put this into any browser and it will produce the list of devices and their corresponding commands. If you desire, you can print this out for your reference.

Additional voice settings

In this section you will set up what additional information the Alexa Enabled Devices respond back to you and how.


Accept Compound Commands

Ask Alexa can accept 'compound commands' as part of its command structure. Simply put, a compound command is controlling two actions with one statement. For example, you could say <"Alexa, tell SmartThings to turn on the office and close the garage"> to have two actions occur in tandem with one command. While this is convenient, the more words you say to Alexa, the more opportunities she has of misunderstanding you. Turning this option off, you disable the ability for Ask Alexa to process compound commands. Only single action commands will be accepted.

Device/Event Voice Setting

In this section you will find items relating to the device voice output along with event voice output.


Give Brief Device Action Reply

Under normal operation, when you give an action to a device, Alexa will respond of a confirmation of your action. For example, if you say <"Alexa, tell SmartThings to lock the Front Door">, if the door is locked already she will state that, or if it is unlocked she will respond "I am locking the front door.". However, if you feel that the responses get tedious to hear, you can turn on "Brief" replies to device actions. When clicking this feature, you have the option of having Alexa reply with nothing, an "Ok", "Done", or a user-defined output. Please note a few caveats to this behavior:

  • For items like locks and doors, the default action is to check the status of those devices and NOT perform the action if the device is already in the desired state. With brief replies turned on, you will not get this feedback.
  • If an error occurs with the device, you will still get the error message if brief replies are activated.
  • If you have battery alerting on (See Ask Alexa#Battery Level below), these messages will append to your brief message.

Please note that the default behavior has been modified slightly (since version 2.2.9) in that the After Action/Event History Continuation commands will be muted when brief reply is turned on.

Speak Additional Status Attributes

For devices like switches or open/close sensors, there are other attributes that can be accessed besides the primary functions. For example, many light switches also monitor the power usage of the connected device. In addition, most SmartThings sensors (motion, water, or open/close sensors) also monitor temperature. Finally, many stand-alone devices, like motion sensors, are battery operated. When you ask Alexa the status of a device, you also have the option to have the additional attributes spoken.

To use enable this option, on the main menu of Ask Alexa find the <<Settings>> option. Tapping this will bring you the <<Settings>> area. Tap the slider labeled <<Speak Additional Device Status Attributes>>.

Please note items that are NOT selected as motion sensors, but have these capabilities, will ONLY report this attribute when motion is in progress.

Device Health

Sometimes the devices in your environment go offline. While there are many causes for this, the end result is that you may attempt to control a device and it is offline without you knowing it. If you enable <<Speak Device Health When Offline>> you will be alerted to the offline status of a device when you attempt to control or query the device. Please note that Ask Alexa CANNOT bring the device back online; this requires manual intervention. In addition, some devices that are tagged by SmartThings on being "offline" simply haven't reported in for a while. Many time, just manually toggling the device (be it a switch, or motion sensor) may be enough to put it back into online status.

Battery Level

This option will allow you to set the threshold in which the batteries status is reported on. The default value of the threshold is 20...using this setting, if the battery level on a device is below 20%, when you ask the status of a device (i.e. <"Alexa, ask SmartThing the status of the living room"> the battery will be reported as well. Above the threshold, no battery status will be given. Please note that battery report is given whether or not the above attributes setting is selected if the level is below the threshold.

Default Number Of Past Events

SmartThings keeps a log on every change on the devices, whether it be a motion sensor showing movement, or a door opening or closing to a light turning on or off. Using the command "Events" on a device you can access the last events (ex. <"Alexa, ask SmartThings to give me the last events on Living Room">). When no number is specified, the number in the <<Default Number of Past Events To Report>> will be used to give you that number of entries from the log. You can override this by giving a number in the command (ex. <"Alexa, ask SmartThings to give me the last 4 events from the Bedroom">)

Enable Flash Briefing

This option will allow you to enable the ability to use a macro or Message Queue as the output of the native Alexa 'flash briefing' function. This process is described here (Ask_Alexa_-_Flash_Briefing) and does require additional steps to create a new skill that allows for this functionality. When you select this option, another option appears below it allowing the selection of the output you wish to use for your flash report.


With a little bit of configuration on this page, you can give Alexa's responses a more "personalized" touch. This includes allowing her to "follow up" after an error, or address you by name in a formal or even funny manner. All of these options also allow you to have them 'whispered' to you all of the time, or within specific modes or timeframes.


Alexa has the ability to continue with a "skill" after the primary function or response is given. With the options in this area, you can choose if you want Alexa to ask "Anything else?" after certain actions have been performed. For example, if you want to stay within the skill after an error comes up (let's say you didn't choose a valid switch), then you would turn on the <<After Error>> option. When Alexa says "Anything else" you do not have to use the <"Alexa, ask SmartThings"> command; simple state your command (i.e. <"Turn on the front porch">). The settings here are global; if you turn them on <<After Errors>> continuation options will be given after every error. Same for the other switches except <<After Macro Execution>>. For Macros, if you have the <<After Macro Execution>> switch turned on, you DO have the ability to suppress this on a per-macro basis. This does NOT suppress any errors that come up within the macro execution (if turned on); they will only suppress the "Anything else?" questions.

Also on this screen you can setup your response "Personality". These personalities will give you different types of responses based ranging for "Normal" to "Snarky" to "Courtesy". For advanced users, these can be customize for your environment/mood. You can also set a name that Alexa will occasionally address you by. The responses are random, so it won't happen all of the time. Again, for advanced users, you can use the text variable %people% (see Ask_Alexa#Text_Field_Variables) to have the responses customized based on who is present in the house. Unfortunately, Alexa has no ability at this time to determine WHO is speaking to her, so the text variable may not be the best solution as it will list everyone in the house.

Playback Options/Restrictions

Under the Global Options of the personality page you will find the playback options/restrictions. Here you can set up restrictions to mute the playback (either disabling Ask Alexa based on the restrictions, or simply mute the playback but continue to process the commands given to it).


In addition to muting playback, Alexa also allows the device to change the voice patterns (speed and pitch) including the ability to 'whisper' back to you in a computerize-light voice. Be warned...this has been called by some "creepy", however, there are specific use cases. Because the volume and the overall tone of whispers is less than normal, you can use these during your 'bedtime' to still interact with Alexa and (hopefully) not wake the person next to you. TO do this, simply turn on the switch <<Enable Whisper Mode>>. Leaving the restrictions below this setting blank means that whisper mode will be enabled all of the time. To restrict this, choose the timeframe and/or mode you want whisper mode to operate in. You can also choose which Echo device to apply restrictions to. All output will then be whispered to you until the restrictions conditions change.


For speed and pitch, there are pre-defined configurations you can choose. Please note that if you change the pitch from normal, you will not be able to use the whisper command. Basically, the pitch command is invalid when whispering. However, speed can be used with the whisper mode. You CAN pick and choose between pitch and speed to create a unique voice response within your household.

   Please Note
   Speed, pitch and whisper adjustments configured on this page affect
   ALL output coming from Ask Alexa. This does NOT affect the output
   of the normal (non-Ask Alexa skill) output. If you want specific '
   Ask Alexa' text to be whispered or emphasized, please use the advanced 
   features of the <<Text Field Variables>> (see Ask_Alexa#Text_Field_Variables)


Other Values/Variables

In this section, depending on your setup, you may have the following options that can be customized by you. The default values should allow for proper operation, but you can change them to suit your needs.


Default Command Values

Some of the devices that use variable numeric numbers to control them (like dimmers, thermostats or volume control) are context sensitive. This means you don't need to give a specific number to increase or decrease their value. You can simply say <"Alexa, tell SmartThings to increase the Living Room by 25%"> and it will rise 25%. However, if you leave off the number, the settings here will be the default amount of the increase or decrease. You can then just say, <"Alexa, tell SmartThings to increase the Living Room"> and it will increase by 20% (the default). You can change these numbers accordingly, but be careful for items like volumes and temperature defaults to prevent hearing or heat damage.

Also, you will see the option for low, medium, high default values. These are good for ceiling fans that operate in 3 different modes, but these settings can be used for lighting as well. Setting these default values will allow you to simply say <"Alexa, ask SmartThings to set fan to medium"> and the fan will go to the percentage you place in these areas.

Finally, if you use Temperature (Kelvin) lights, the values for "Soft White", "Warm White", "Cool White" and "Daylight White". If you do not change these numbers, the defaults will be used (2700K, 3500K, 4500K and 6700K, respectfully).

Device Minimum/Maximum Values

For devices with variable inputs that are critical (i.e. volumes, or temperature controls), Ask Alexa allow you to set minimum and/or maximum values for some of these parameters. For example, a speaker may not need to ever go above 20%...placing 20 in the maximum value slot will prevent your from purposely (or by a misunderstanding from the Amazon TTS system) from setting the volume above this value. In contrast, you may not want to allow your thermostat to be set less than 60 degrees...putting this number in the appropriate slot will prevent any settings from going below that value.

Text Field Variables

These global variables are words (typically starting and ending with a percent sign...for example %temp%) that can be used in any text fields of the macros/extensions to give you 'short cuts' to commonly used text. These make it convenient to personalize the messages coming from the Alexa Enabled Devices, macros and extensions.


A full list of the current variables available to use are here:

Text Field Variables used in pre/post messages and macro acknowledgement areas
Variable Translation
%time% This will give the time in 12 hour, AM/PM format
%day% This will speak the day of the week (Monday, Tuesday, etc.)
%date% This will speak the full date (ex. January 25th, 2016)
%temp% When a single device is selected (defined in the temperature report area) the device will report that temperature. If multiple devices are selected, it will average the readings and report the average.
%humid% Similar to the temperature reading above, when a single device is selected the device will report that humidity. If multiple devices are selected, it will average the readings and report the average.
%people% These are defined by presence sensors that are currently present. Using this variable you can personalize some of the responses the Alexa devices give. You can also use this variable when setting up your personalized feedback (See Ask Alexa#Personalization)
%macro% This is the name of the macro/extension that was called.
%mtype% This is the type of macro/extension being called (i.e. Room/Groups, Control Group, WebCoRE, etc)
%delay% For macros such as WebCoRE and Control macros, this variable holds the delay (in minutes) that was specified within the app or verbally.
%age% For the Schedules extension, this variable holds the age of the schedule (i.e. the person's age or anniversary years) if the original year of the event was defined.
%random{1-3}% When you set up the 3 categories of random responses, placing this variable in a text field will randomly choose a response and play it.
%xParam% For WebCoRE. Extra parameters of control

For example, if you are giving a nightly report right before you go to bed and you wish to personalize the message, your post message could be something like:

It is %time% on %day%, %date%. It is time for bed %people%. %random1%.

This would result in something like "It is 9:00pm on Monday June 23, 2016. It is time for bed Jim and Jane. Sleep well...Good night.". In this particular example, the time and date have been replaced with real time information. The %people% variable is determined by who is present from the presence sensor readings you set up in the main menu <<Setting>> area. Finally, the %random1% list is 3 good night phrases that you have defined. The other two could be "Don't let the bed bugs bite" or "Talk to you in the morning". Anything can be put into these areas.

In addition to the built-in variables, advanced users have the ability to reference weather reports using a variable. Simple surround your report name with percent signs, and this variable can play in any extension text field. This is very useful for voice reports where you want to include a weather report.

Finally, there are other advanced flags available ('on-demand whispering', 'emphasis' and 'suppress continuation messages' ) that can be used in text fields.

The 'on-demand whispering', 'emphasis' tag tags ONLY works if you have the Global Whisper Functions function turned off in the <<Personalization>> section (see Ask_Alexa#Personalization). This will allow you designate parts of the output as regular and parts as whispers and yet other parts emphasized.

The 'suppress continuation messages' is only used in macros/extensions when continuation of commands (see Ask_Alexa#Personalization) is enabled for macros/extensions. Basically, placing this tag at the end of the custom acknowledgement will suppress the prompt "Is there anything else?" placed at the

To use these features, here is the formatting:

Advanced Tags used in pre/post messages and macro acknowledgement areas
Tag Usage
<w> Any text between here and the "off" switch (below) will be whispered
</w> Any text between the above and this tag whispered
<eH> Any text between here and the "off" switch (below) will be highly emphasized
<eL> Any text between here and the "off" switch (below) will have lower emphasis
</e> Any text between either of the above switches and this tag will be emphasized as outlined(H or L)
%X% Used for macro/extensions custom acknowledgments. Will suppress any output from continuing commands

For example, let's say you have a voice report that has following custom acknowledgement:

"And that is all. <w>Have a good evening</w>. <eH>Don't let the bed bugs bite!</e> %X%"

The section encapsulated by the <w> </w> will be whispered and the text between <eH> </e> will be highly emphasized (slowed down and volume increased) while the other parts will play based as normal. In addition, with the %X% at the end the additional text of "Would you like anything else?" will be suppressed; however, Alexa WILL remain active, listening for any additional commands that can be used within Ask Alexa.

Custom Color Setup

If you have no colored lights in your SmartThings environment, you will not see this selection. If you have chosen any colored lights you will have the option to set up a custom color. Simply give the name of the custom color, the hue and then the saturation of the color (A good reference for hue and saturation is here[12]. You will need to ensure you update your developer slots when you have saved this name, but after you do you should have access to this color when utilizing colored lights.

xParams For WebCoRE Macros

If you use Ask Alexa to run WebCoRE macros and need to pass a word parameter to the piston, you can now (as of 2.3.7) maintain your list of xParams via the SmartApp instead of manually inputting them to the Developer's slots (Under LIST_OF_WCP). More information can be found about passing variables here: Ask_Alexa_-_Macros#Advanced_features



In this section you can set up security related items such as PIN numbers, or to revoke your Access Token.


Revoke/Reset Access Token

It may be necessary sometimes to revoke your Access Token and issue a new one. Typically, this is required when you publicly post the ApplicationID or TokenID to a public site as this would allow others to access your home environment. Once you reset your token, you will need to place the new code pieces into your Lambda code (See Ask_Alexa#Finalizing_The_Function_Code).

To proceed with the reset, simply tap the area labeled <<Revoke/Reset Access Token>>. Here, you will be given one last opportunity to cancel this process as doing so will disable the ability for Ask Alexa to control your SmartThings environment.

Password PIN

While one of the strengths of the Alexa Enabled Devices is the voice recognition; one of the weaknesses is that the device has a difficult (and inconsistent) ability to differentiate one person from another. In most household, the Alexa Enabled device is shared among many people. This makes security of commands on the device almost non-existent. For example, imagine a banking app that speaks your bank balance. If you were to have a dinner party, anyone at the party that was savvy enough with the Alexa Enabled Devices could access your bank balance as easily as you. While there is "security through obscurity" in the fact that Ask Alexa is community built and not mass market, in theory, a person familiar with your home system could yell through a window and say <"Alexa, ask SmartThings to open the garage door">. To prevent this and provide some level of security, Ask Alexa implements a basic PIN system for security items like doors, locks, modes, routines, SHM, and macros that control these items.

To use this feature, in the Ask Alexa SmartApp find the <<Settings>> menu item, then tap the the on/off slider labeled <<Password (PIN) Option Enabled>>. This will reveal an area to enter a PIN number. Be sure to enter numbers in this area. Then, while setting up various items like lock, modes, or control macros, you will be given the option to use the PIN for that function. You can also 'fine tune' this security by adding restrictions, such as the day of the week, or even which Echo devices require a PIN.

To use this new PIN in the context of opening the garage door, simply say <"Alexa, ask SmartThings to open the garage door password 1234"> (assuming you chose 1234 as your PIN). You will always append your commands with the password. Putting it in other locations throughout your syntax may not give the desired results. If you fail to issue the PIN command, you will be prompted by any device or function that requires a PIN to supply this information. This follow up is as simple as <"Password 1234">


In this section you can enable some of the advanced features of Ask Alexa.


Allow Device Aliases

To allow devices to have aliases associated with them, enable this option. This will do two things to the main menu interface; first, each device category will have a new area to allow devices to be set up as aliases. Second, once devices are selected, the main menu will display the <<Device Aliases>> area, allowing you to set up the aliases with the devices you have selected. See Ask_Alexa#Interface_Items for more information.

Assign A Name

If you have a need for changing the default name of the SmartApp (Ask Alexa) you may do this using the <<SmartApp Name>> area. This does NOT have any other other affect on the app except to change the name as seen in your SmartThings main app menu. When used with a multi-room setup, you can easily identify the correct app to set up for specific rooms (see Ask_Alexa#Multi-Room_Controls_.28Advanced.29 for more information.)

About Ask Alexa

The about page gives basic information about the Ask Alexa app and other parameters you may find useful. You may also produce a "cheat sheet" that can be printed for those not familiar with the setup of the SmartThings environment or your Ask Alexa configuration.

In the <<Version Numbers>> section, you will find the versions of the SmartApp and the Lambda code. You can also hear the version numbers of the SmartApp and Lambda code by asking <"Alexa, Ask SmartThings about Versions">.

In addition, this page displays your current Access Token and Application ID. This is useful for troubleshooting only and should be kept private to prevent someone else from controlling your house. Below this is the list of your Echo devices that have been associated with rooms.

The Apache license is available on this page as well, along with some basic instructions.

At the bottom of the page you will find a section to produce a list, or "cheat sheet" of all of the devices (and aliases) that are set up within Ask Alexa.

AAHelp.png AAHelp1.png

While tapping this section produces the list on your mobile device, you may want to render this on a computer browser to allow you to print this page out. To do this, have your IDE Live Logging active. When you open the page you will see a link. This is similar to the link you acquire the setup variables from (See Ask Alexa#Setup Variables)


Once you have the link, put this into any browser and it will produce the list of devices and their corresponding commands. If you desire, you can print this out for your reference.

Finally, if you choose to remove this application (and the corresponding macros), you may do this at the bottom of the page. Simply tap <<Remove>> and the application will be removed from SmartThings. If you choose to set up the app again, you will need to go through the entire setup process again.

Developer and Lambda Code Installation

The next step is to install the ASK code to the AWS/Lambda server and to define the custom intents, slots and utterances. You will need both an Amazon developer account and an AWS Lambda account. Creation of these accounts is outside of the scope of this document, however, very clear instructions for starting these accounts can be found here: Developer Account and Lambda Account

AWS/Lamba Code

The basic steps for generically creating Lambda code is listed here [13]. Many of the same steps are listed below as well.

  • First, be sure you Lambda account is set to the proper region. The Alexa skills are currently only supported from the <<US East (N. Virginia)>> <<US West (Oregon)>> and <<EU West (Ireland)>> region. Failure to do choose the correct region will prevent you from properly setting up the Configure Triggers (Ask Alexa#Configure Triggers)


  • Next, find the area within the AWS dashboard for Lambda. This may be a button on the main screen or within the menu below <<Compute>>.


  • Find the button labeled <<Create Function>>. Click this and you will begin configuring the parameters of the function.


  • You will be brought to a screen to choose a blueprint. Choose <<Author from scratch>> and click it.


From here you will enter a name of the function (it is recommended to use "askAlexa")

For the area labeled <<Run Time>> it is recommended you set this Node.js (version numbers may be present...always choose the current one), then choose a role or use an existing role. It is recommended that you choose a Existing Role and select "lambda_basic_execution". If you do not have anything listed in the "Existing Roles" do the following:

  • In the role, choose Create a custom role
  • A new screen will show up
  • In the IAM Role, choose lambda_basic_execution
  • Keep the policy name as default
  • Click the Allow button in the bottom right corner of the screen


When you return to the previous screen and you have configured everything like the screenshot below, click <<Create Function>>.


Configure Triggers

Next, you will be brought to a page where you choose what type of trigger you are creating. On the left side of the screen there is a section called <<Add Trigger>> and here you will choose the "Alexa Skills Kit".

If you are asked to configure your trigger (specifically with Skill ID), for now choose "Disabled", then <<Add>> in the bottom right of the screen and then click the skill name at the top of the page (above the Skills kit and CloudWatch Logs).


   Please Note 
   If you don't see Alexa Skills Kit in the list, you have chosen the wrong region. 
   You must use theUS East (N Viginia), US West (Oregon) or the Ireland datacenters. 
   Once you have selected Alexa Skills Kit, click <<Configuration>> to go back to the main code 
   section of the function.

From here you can enter your code. See the next section (Configure Function) to choose two different methods for entering your code into this area.


Configure Function

After version 2.3.5a there are two methods you can use to get the correct information into the Lambda code: A process where you simply click a link on the Setup Variables page, and a more manual method where you paste the authentication information from the Setup Variables page to the Lambda code.

One-Step Method

The one-step method is, by far, the easiest way to get the needed information to your Lambda code. Obtain the code for your configuration, follow these steps:

  • In the Ask Alexa Smartapp, click <<Settings>><<Setup Ask Alexa), then <<Setup Variables Link>> (see Ask_Alexa#Setup_Variables). Please note you should be using a desktop browser to do this.
  • Find the buttons to obtain the Lambda Full Code:


  • Clicking this link will bring up the raw code, customized with your authentication information already embedded in it. Simply select all the text in the browser (typically Clt+A), then copy it (Ctl+C), then paste it into the proper location.


  • Save the code and you are done!
Two-Step Method

For those that want to do the installation manually...

In this step you will need to supply the code with your unique Application ID and Access Token. The app will generate this for you either in your mobile device or via a desktop/laptop browser. See Ask_Alexa#Setup_Variables for more instructions to obtain this.

  • Obtain the code from From here:
Ask Alexa Code Area Used Version Location
Node.js Lambda code for 1.3.1a
  • Paste the code here:


  • In the Ask Alexa Smartapp, click <<Settings>><<Setup Ask Alexa>> then <<Setup Variables>> (see Ask_Alexa#Setup_Variables). Please note you should be using a desktop browser to do this.
  • At the top of the HTML setup page that is generated, you will want to copy the first 3 lines below the title <<Lambda code variables>>.


   Please Note
   While the web address (URL) to the SmartThings environment should remain constant, it could be different 
   than what is displayed about depending on the country you reside in. In addition, this address is
   subject to change at any time. The Ask Alexa app uses the SmartThings API to generate this address
   when you run the setup page.

   If the app stops working suddenly, please ensure these parameters in your setup web page
   match the Lambda code you pasted when you set up this function.
  • Next, paste the lines between the two commented areas (breaks) at the top of the code area.


Failure to copy these lines exactly will prevent the Lambda code from accessing your SmartThings environment. When you have completed copy (or any time you modify the Lambda code, be sure to click Save in the upper-left corner of the screen).

   Please Note
   Do not press the <<Test>> or <<Save and test>> buttons in the AWS Lambda area.
   Doing so will not cause any problems, but Lambda works on specifically formatted 
   inputs and unless you supply these inputs exactly to the test it will always present 
   you will an error. This error is not valid and this recommendation is simply 
   made to avoid confusion when setting up the code.

ARN Code

  • When everything is configured properly and saved, you will find in the upper right-hand corner of the screen an ARN. This is your Amazon Resource Name and will link your function with a corresponding Skill. It is recommended you copy this number or keep your screen open when you are creating the Skill in the developer area below.


Developer Account (Primary Skill)

You will now need to define the primary skil using an Amazon developer account. Be sure you have followed the instructions from Amazon on setting up your developer account: Developer Account.

   Please Note
   In order to easily test and use your new "skill" it is recommended that you create
   your developer account under the same account you used to set up your Alexa device.
   If you already have a developer account that is different than your Alexa device account, 
   you must assign your physical device to the developer account and then associate 
   your personal account as a "household" under your development account. More information
   on this process can be found here.


  • On the Alexa Skills Kit Developer Console, click <<Create Skill>>

Building The Skill

  • The first page you will be presented with is the Skill Name. Typically, it is recommended to use Ask Alexa - SmartThings Integration
  • Next, you will be presented with a page with pre-built models' however, you will choose a <<Custom>> skill. Select this option, then click <<Create Skill>> in the upper-right corner of the page.


  • Here, you will be presented with options to build your skill. On the right side of the page you will have the various steps required to create your skill. These include Invocation Name, Intents, Samples, and Slots, Build Model, End Point.
  • To begin, click <<Invocation Name>>


  • While the name can be anything you want, it is recommended to start off with 'smart things'. Other options include words like 'house', home, etc.
   Please Note 
   The Invocation name should be typed in lower-case. If you like to use the word SmartThings
   as the invocation name, it is recommended you type 'smart things' (not 'smartthings'). 
   Also note that the invocation name within your SmartApp (here: Ask_Alexa#Personalization)
   should match this name. This is important if you use the Ask_Alexa#Single_Step_Interaction_Model
   to set up your Amazon developer area.
  • After you have entered your Invocation Name, click, <<Save Model>> at the top of the screen. Then click <<Custom>> on the left side of the screen.


  • You should now see your invocation name with a check mark next to it.
  • Next, on the Skills main page, find the <<JSON Editor>> on the left side
JSON upload


  • Just like the Lambda code setup (see Ask_Alexa#One-Step_Method) you will click the link for the Developer Code (Second bold line).


  • Alternatively, you have the option to download the Developer Code (JSON) as a text file. Please note the file name will have a timestamp on it and may be different than what is shown below. This is the recommended way of doing this INSTEAD of copying/pasting the JSON code.
  • Select all of the code from webpage, copy it, and then paste it into the Amazon Developer's page. If you chose to download the JSON text file, click the area as shown below, choose the file you downloaded, and click Open. After either (not both) of these steps, click <<Save Model>> in the upper-left corner of the page. Then click <<Build Model>>. Be sure to watch the upper-right corner of the screen to status messages, including any errors that may occur.


Once the build is completed, click <<CUSTOM>> on the left side of the screen, you will now see steps 1, 2 and 3 on the right side with a green check mark. Click on <<4. Endpoint>>


  • On the next step, you will enter the ARN number from the code from the AWS/Lambda area (See Ask_Alexa#ARN_Code). Place this code in the <<Default Region>> Area


  • Click <<Save Endpoints>> at the top of the screen. Next, click on <<Interfaces>> on the left side of the screen. Ensure your page looks like the screenshot below. Click <<Save Interfaces>> and <<Build Model>> at the top of the screen.


  • Click on Account Linking on the left side of the screen. Ensure the toggle switch is off.
  • The final step is to click <<Permissions>>. This will be set according to the screenshot below with all of the items toggled 'off'


Testing Your Skill

If you followed the directions properly, you should be ready to test your new skills.

  • Click <<Test>> at the top of the Skill Console.
  • Ensure the <<Test is enabled for this skill>>. While this implies that only testing is impacted, this slider actually disables the operation of your skill using your voice. This must be turned on.


  • As mentioned above, your Alexa Enabled Devices should be associated with your developer account. Please see here ([[14]]) if you did not do this.
  • If properly set up, if you go to the <<Skills>> area of or the Amazon Echo mobile app and refine the view to <<Your Skills>>, you should see your new Ask Alexa Skill.


  • Start speaking to your Alexa Enabled Device. Start with "Alexa" (or your wake word), along with "ask" or "tell" along with the invocation word, followed by what you want to do.
  • Start with a simple switch (example: Living Room) and say <"Alexa, ask SmartThings to turn on Living Room">. The Living Room should come on. If not, please check all of your settings. You may also visit the SmartThings Community for this app ( to ask community members (and sometimes the author) questions about this app. Finally, use the Ask_Alexa#Troubleshooting section for additional advice on how to troubleshoot your issues.
  • If your test goes well, try your other devices. In addition to the voice feedback, you should also also see 'cards' appear in your Echo mobile app to give you an indication of what the device is hearing and the responses it gave.


  • If you have difficulty, you may be able to troubleshoot the application yourself. The Amazon developer web site has tools to allow you to simulate your commands and show you what the responses are. Using this along with the SmartThings Live Logging should allow you to figure out where your issue is.
  • While on the Amazon Developer site, under the Test area, you can type your commands into this simulator to give you access to the skill. Be sure to type your invocation name when using the simualtor (i.e tell smart things version )


  • JSON text will appear on the simulator boxes. The left side JSON is useful to see what was input, with right which includes the response from the SmartThings app and presented to the Echo device.
   Please Note
   In order for community members or the author to properly troubleshoot this application
   it will be important for you to produce screen shots of your environment. Please ensure
   you have provide screen shots of not only the development web site, but the Live Logging
   area of the SmartThings IDE so that issues can be quickly resolved.

Launch (Optional)

While optional, you can add icons to your application that will be visible in the Amazon Echo stand alone application on your mobile device, or at On the skills console page, click <<Launch>> at the top of the screen.


The recommended text is outlined below, but again, this is completely optional and is not needed for proper usage of the application or the integration with SmartThings. When you are completed.


If you choose to use the supplied icons, their locations are listed here to download and use.

Icon Size Location
108 x 108 icon
512 x 512 icon

Click <<Save and Continue>> at the bottom. Please note that you should stop here with your skill. The next steps in the interface are for publishing the app for others to use....something you DON'T want to do unless you want the world to control your home.

Developer Account (Secondary Room Skill)

Coming Soon

Ask Alexa Usage

Assuming you kept your invocation name as "SmartThings", the usage of Ask Alexa is as simple as this: <"Alexa, ask SmartThings to unlock the front door">. The invocation of "tell" or "ask" are required to activate the custom ASK Skill. However, they have no other context within the command. In other words, you can 'ask' or 'tell' Alexa the same command and she will respond exactly the same way.

Asking/Telling Alexa What To Do

Just like human language, the Alexa Enabled Devices will key off of nouns and verbs. The nouns are the device names (or aliases), modes, or routines you have set up in SmartThings. Verbs are the actions (or operations) you would like to carry out. However, just like human language (especially English), the rules are not hard and fast. It is recommended you try different combinations of syntax to get the results you desire. If you come up with a unique one, contact the author of this application so that the "intelligence" of the application can continue to grow.

Please note that while most of the utterances begin with <"Alexa, ask SmartThings...">, there are also other valid ways to address the Ask Alexa functions. For example, instead of saying <"Alexa, ask SmartThings to turn off Dining Room">, you could say, <"Alexa, turn off Dining Room with SmartThings">. If "asking" or "telling" Alexa something doesn't feel natural with the "SmartThings" invocation word at the beginning of your command, try another combination with putting <"...with SmartThings"> or <"...using SmartThings"> at the end of the command. Even "use" can be used (pun) to activate the skill (ex. <"Alexa, use SmartThings set the Thermostat to auto mode">

  • Switches/Dimmers/Colored Lights: on, off, toggle, status, level, color, increase, decrease, rise, lower, up, down, maximum, minimum, low, medium, high
    • <"Alexa, tell SmartThings to turn on the living room">
    • <"Alexa, ask SmartThings to turn on the living room">
    • <"Alexa, ask SmartThings to increase the level of the living room"> - Without a numeric settings, "increase" or "decrease" commands will be based on the values you set up in the <<Settings>> area.
    • <"Alexa, tell SmartThings to lower the level of the Living Room by 5%"> - You can specific the amount of the increase or decrease of the brightness level.
    • <"Alexa, tell SmartThings to set the Media Room to Blue and 30%">
    • <"Alexa, tell SmartThings to set the Media Room to Red"> The light will stay at the current level if not specified.
    • <"Alexa, tell SmartThings to set the Bed Room to medium"> - "Low", "medium" or "high" commands will be based on the values you set up in the <<Settings>> area.
    • <"Alexa, ask SmartThings to set Lamp to maximum"> - "Maximum" will set the dimmer to 100%.
    • <"Alexa, tell SmartThings to set the Bed Room to medium and green"> - You can also use two commands in unison as shown here.
  • Doors/Locks/Shades: lock, unlock, open, close, status
    • <"Alexa, tell SmartThings to open the front door"> - Please note that if front door is a connected lock, OPEN will NOT unlock the door. Open and Close are reserved for items that have motorized open/close mechanisms.
    • <"Alexa, ask SmartThings to open the garage door password 1234"> - assuming you chose 1234 as your PIN; see Ask_Alexa#Password_PIN for more information.
    • <"Alexa, ask SmartThings the status of the garage door">
  • Thermostats/Temperature/Humidity: set, status, heat, cool, heating, cooling, mode, off (for StelPro baseboard heaters, eco and comfort modes also available), home/away (For Nest Thermostats), get/repeat/replay/get/load/reload/restart/erase/delete/clear/reset tips (Ecobee Thermostats)
    • <"Alexa, tell SmartThings to set the bedroom to 55 degrees"> - It should be noted, depending on your thermostat, you may need to append the command with heating or cooling for multi-setpoint thermostats in auto mode.
    • <"Alexa, tell SmartThings to set the bedroom heating to 55 degrees"> - Same as above, but just sets the heating setpoint
    • <"Alexa, ask SmartThings to turn on bedroom heating mode"> - For thermostats that have separate heating/cooling/auto mode
    • <"Alexa, ask SmartThings to turn off Bedroom"> - In this context, when bedroom is a thermostat and NOT a switch, this will turn the thermostat off (from heating/cooling or auto mode)
    • <"Alexa, tell SmartThings to lower the temperature of the living room by 5 degrees"> - You can specific the amount of the increase or decrease of the temperature setpoint (the value will be based on the current temperature...not the current setpoint).
    • <"Alexa, ask SmartThings to raise the temperature of the den"> - If no value is given, an increase or decrease in temperature (based on current temperature) will default to the value in the <<Settings>> menu.
    • <"Alexa, ask SmartThings set the Hallway to auto mode"> - In this context, when hallway is a thermostat and NOT a switch, this will turn to auto mode. Auto mode will require you to set the temperature setpoints using the 'heating' or 'cooling' command.
    • <"Alexa, ask SmartThings the status of the Back Patio"> - in cases like this, it is better to ask the status of a device and not temperature specifically.
  • Other Sensors: status
    • <"Alexa, ask SmartThings the Bathroom Floor status">
    • <"Alexa, ask SmartThings about Michael"> - In this context, Michael is a presence sensor. You will receive a response of "present" or "not present".
    • <"Alexa, ask SmartThings about Kitchen Sink"> - Notice that just the noun can be used and the "status" is assumed in most cases.
  • Modes/Routines/SHM: run, execute, status
    • <"Alexa, tell SmartThings to execute the Good Morning routine">
    • <"Alexa, ask SmartThings the status of the current mode">
    • <"Alexa, tell SmartThings good night"> - Assuming you have a mode or routine called "Good Night", Ask Alexa will run this mode or routine (please note you must have unique names for modes and routines to use Ask Alexa properly).
    • <"Alexa, mode status from SmartThings"> - Notice how the invocation word is at the end.
    • <"Alexa, ask SmartThings about security"> - This is another way to ask about status of Smart Home Monitor.
    • <"Alexa, tell SmartThings to set security to disarm"> - please note for the Smart Home Monitor you can also use the noun "security"
  • Voice/Weather Reports: run
    • <"Alexa, use SmartThings to run the Nightly report"> - Notice the word "use" to activate the skill.
    • <"Alexa, Battery report from SmartThings"> - Notice how the invocation word is at the end.
    • <"Alexa, ask SmartThings for the weather"> - assumes the name of the weather report is 'Weather'.
  • Macros: run
    • <"Alexa, tell SmartThings to set the Media Room Group to 30%">
    • <"Alexa, tell SmartThings I am going to bed"> - Please note the creative naming of the control group in this example (Name: "I am going to bed")
  • Message Queue: play, open, delete, clear, erase, status
    • <"Alexa, tell SmartThings to play messages"> Without a queue referenced, the primary message queue will play back
    • <"Alexa, tell SmartThings to open {queue name} queue">
    • <"Alexa, ask SmartThings to clear message queue"> As above, without a queue referenced the action will happen on the primary message queue
  • Connected Speakers: play, pause, stop, mute, unmute, next track, previous track, status
    • <"Alexa, ask SmartThings to play Bedroom Speaker">
    • <"Alexa, tell SmartThings to mute Living Room">
    • <"Alexa, tell SmartThings to increase the volume of the Office"> - When no value is given, the increase or decrease will default to the value you set up in the <<Settings>> area.
    • <"Alexa, ask SmartThings about the Guest Room Speaker status"> - Please note below about querying the status of Sonos speakers
   The Sonos integration within SmartThings is currently in listed as a "Labs" .
   release. This means certain functionality is subject to change or may not work as
   expected. For example, if you manually play the Sonos and then ask Alexa about the 
   status of the speaker, she may say the speaker is stopped. This is because the Alexa 
   Enabled Device is pulling the status of the speaker from SmartThings, not the speaker itself. 
   So, there is typically a 1 to 5 minute delay before SmartThings refreshes the speaker
   status. However, commands that YOU issue to the Sonos device are activated immediately.
  • Schedules: on, off, status
    • <"Alexa, ask SmartThings about Doctor's appointment">
    • <"Alexa, tell SmartThings to turn off Golf Lesson">

Ask Alexa Help/List Commands

Obviously, the main purpose of an application like Ask Alexa is to NOT grab your phone everytime you want to make turn on a light or turn up the speaker. However, humans are visual creatures so it is sometimes difficult to remember the specific name of a device you have included to interface with enabled device without some sort of reminder. Ask Alexa has a basic help function to guide you through which devices, modes or routine commands you can use.

Please note that having Alexa call out every device and operation can be time consuming to listen to. If you need her to stop speaking, simply say <"Alexa, stop!">.

  • Basic help
    • <"Alexa, ask SmartThings for help"> - This is just an overview of the application usage. At the very end you can confirm what version number of the Lambda code you have running.
  • Lists - simply issuing a 'List' command and the type of device/operation you want help on will issue a list of what is interfaced with Ask Alexa.
    • <"Alexa, list switches in SmartThings"> - Notice how the invocation word is at the end.
    • <"Alexa, ask SmartThings to list switches">
    • <"Alexa, tell SmartThings to list modes">
    • <"Alexa, ask SmartThings switch list">
    • <"Alexa, ask SmartThings about the control macros">
    • <"Alexa, ask SmartThings to list humidity sensors">
    • <"Alexa, ask SmartThings about the reports">
    • <"Alexa, ask SmartThings about SHM">
    • <"Alexa, ask SmartThings about the dimmers"> - Notice that when asking about a key word noun (dimmer, switches, etc) you can leave off the list.
    • <"Alexa, ask SmartThings to list the colors"> - This option is available if you have colored lights listed within the Ask Alexa SmartApp on your mobile device. Please note that the colors list is generated from SmartThings and is quite extensive. It would take over a minute to list the colors, so instead you will be referred to the Ask Alexa cheat sheet for the full color list.
    • <"Alexa, ask SmartThings to list the colored lights"> - Please note that this is different the command above. This will give you the list of available colored lights available to control.
  • Version-You can get the version number of the various pieces of Ask Alexa
    • <"Alexa, version of SmartThings"> - Notice how the invocation word is at the end.
    • <"Alexa, ask SmartThings about Ask Alexa">
    • <"Alexa, ask SmartThings about the SmartApp">
    • <"Alexa, ask SmartThings about versions">
  • Repeat- You can request the last thing Ask Alexa said to you (no action is done, just repeat the last results)
    • <"Alexa, tell SmartThings to repeat">
    • <"Alexa, ask SmartThings again">
    • <"Alexa, ask SmartThings to replay">

There is also a special 'list' that can be retrieved from Device Group Macros (Macros that control groups of similar devices, like switches) and Macro Groups (A macro that runs groups of other macros). Examples include:

  • <"Alexa, tell SmartThings to list HouseMacros"> - In this context, "HouseSwitches" is a macro groups with child macros included. This command will list the child macros controlled by this group macro
  • <"Alexa, tell SmartThings to list HouseSwtiches devices"> - "HouseSwitches" is a device group macro. This command will list the devices controlled by this macro

Use Cases

Below are some examples of use cases on how you can use Ask Alexa to its full advantage.

Natural Language Responses

Using a control macro, you can simulate a little bit of intelligence using Ask Alexa. For example, if you have a room with a few dimmers you could set up a couple of macros called "It is too bright" and "It is too dark". In each of these macros you would set up the dimmers (SmartThings Devices Area) you want to change, and put a default increase/decrease in the provided area. At the bottom of each page you could put in a custom response such as "I have increased the brightness for you". Then, when you say <"Alexa, tell SmartThings it is too bright"> or <"Alexa, tell SmartThings it is too dark"> and it will increase or decrease the lighting as you requested. Using macro aliases you could use different versions of the phrasing and react accordingly without creating multiple macros for the same action. Future version of Ask Alexa will allow this type of control for more devices (such as thermostats).

Good Night Weekdays/Weekends (Invocation)

Using the control, WebCoRE Trigger or voice report restrictions, you can use a single voice command to have multiple outcomes. For example, let’s say you set a different mode on the weekdays than on the weekends when you go to bed. To accomplish this you could set up two control macros; within the first macro you restrict it to run Sunday through Thursday and sets a mode called "Wake up on", and the second only runs on Friday and Saturday and sets a mode called "Wake up off". You would then create a extension group called "Good Night" which includes the first two control macros (no specific order is needed). Each night you could say <"Alexa, tell SmartThings Good Night">. This would allow the same command to be issued nightly but behave differently depending on the day of the week. In the morning, a program such as Talking Alarm Clock could key off of the Alarm on/Alarm off modes and react accordingly. If you are using restrictions as part of a extension group you should also click the <<Mute Restriction Messages In Extension Group>> (in the individual macros) to eliminate unwanted restriction warnings within the running of the macros.


Good Night Weekdays/Weekends (Native, Non-Invocation)

Similarly to the process above, you can use the native Alexa Routines, along with Ask Alexa, to accomplish the same results without having to utilize the skill directly. The steps are similar to above: First, just like above, you set up two control macros with the similar weekday/weekend restrictions. You will also create the same extension group which includes these control macros. The difference here is that you will create a virtual momentary switch (using an app like Alexa Virtual Switch Creator [15]). In this example, the switch is named "Good Night Trigger". Going back to the extension group, you enter this virtual switch in the area labled "Switch trigger for this macro".


In your Native Alexa App, you will then create a routine called "Good Night". You can add a weather report or any other function you'd like, but the most important piece is to include turning the "Good Night Trigger" switch on. Saving the routine and simply saying <"Alexa, Good Night"> will set the mode to the correct setting based on the day.


Please note that any output you included in the macros or extension group WILL NOT play on Alexa. You can use a message queue and an external speaker to play any output you desire.

Weather Reports and Advisories

Full weather advisories can be lengthy, and if you include them with EVERY other possible weather message (temp, location, lunar, etc.) you are almost guaranteed to exceed the default Lambda timeout (3 secs), and you'll probably exceed even a 10 second timeout if there are multiple alerts for your area. Because of this, you will need to extend your timeouts (if you want to receive the exhaustive Weather Report). Please see below for extending the timeouts. Another solution is to break your Weather Report into 2 separate reports. The first (maybe called "Weather Report") should have everything you want enabled EXCEPT the Full Weather Advisory - you'll get a notice telling you there are one or more Advisories, but not the advisory text. And the second (called "Weather Advisories") has only the temperatures, the <<Full Weather Advisories>>, and the <<Speak Location>> enabled. So, when you run your Weather Report you will hear there are advisories, and then when the report is done, you can ask Alexa to run the Weather Advisories report.

Future versions of Ask Alexa will allow you to schedule a periodic check of advisories and actually push them to the message queue, which would allow for visual and audio notifications.

Basic Control Of Two Homes

By virtue of how SmartThings and Amazon implement security with their devices, you can typically only control one home's SmartThings devices with the Alexa Enabled Devices in that home. However, you can actually control devices in two different locations using a single Alexa device in each home. This use case assumes you have two SmartThings accounts (or locations) set up.

To accomplish this, you first need to identify what you want to do at the remote location. This could be simply activating a switch, etc. For simplicity sake, let's use "Home A" and "Home B" as the homes you are working with, with devices, modes or routines listed as "Device A", "Mode A", "Routine A" etc for Home A, and "Device B", "Mode B", "Routine B", etc for Home B. Using this terminology, let's assume you want to control a routine in Home B from Home A's Alexa Device. Using Home B's Ask Alexa implementation you would set up a Control macro that runs Routine B, then obtain the REST endpoint of the macro in Home B you want to run (see below). Next, in Home A's Ask Alexa SmartApp, you will set up a Control Macro that includes the REST URL in the <<Run this HTTP request...>> section. Then when this Control Macro is run from Home A, Home B's devices will react. There is currently no way to currently gather status feedback from one home to another, however.


Multi-Room Controls (Advanced)

   Please Note
   This process requires a bit more effort to accomplish than a normal install.
   It is recommended you become familiar with the full home control before you
   attempt to do a multi-room install.
   This install does have caveats; message queues still operate, but sending apps
   may be confused with multiple rooms set up.
   Use the multi-room setup with careful consideration on the benefits vs the

While most users will desire to control their entire home with one invocation name (typically "SmartThings" or "Home"), Ask Alexa has the ability, with a bit of work, to have a multi-room setup. Consider the following use case:

You have a large home and routinely have guests over. You want the guest, when in their room, to be able to control the devices within that room without controlling the other rooms or controls in the house. While this is possible in a single-room setup using aliases and macros, this might become confusing. And, this wouldn't prevent the users in that room to do a device or command list and finding out the names of the other devices around the house.

Instead, the guest in their room could say, <"Alexa, turn off the lights in this room"> and the lights in that specific room would go off. If they request a list of devices or commands, only the devices you set up in that room will only be listed.

To accomplish this, you will need to do the following:

  • For each "room" you will need to have a separate app for that room
    • You will need to change the line in the Ask Alexa IDE from "singleInstance: true," to "singleInstance: false," (this is currently line 26 in version 2.2.2)


    • You will load up another version of Ask Alexa from the SmartThings Marketplace. It is recommended that you change the display name under Settings>>SmartApp Name to "Ask Alexa {room name}. Be sure to use the example name in the invocation name example (<<Settings><<Setup Ask Alexa>><<Invocation Name>>) to the name you set up for the room as the skill name.

AANameAdv1.png AASetup.png

  • For each "room" you will need to create a separate Lambda function
    • For each instance of your SmartApp, you will need to associate the Oauth and Token with your Lambda code.


    • Each Lambda section will have its own unique Oauth and Token from the individual app
  • For each "room" you will need to create a separate skill.
    • You will name the invocation name the name of the room (placing, for example "this room" where "smart things" is below)


    • Each skill will require the ARN number from the associated Lambda function

Tips and Tricks

  • The naming of your devices is extremely important for proper usage of Ask Alexa. If you have two devices named "Living Room" for example, if you ask to turn on that switch and a temperature monitor is also named that same thing, you may not get the results you desire. It is good practice to choose devices to use with Ask Alexa that have unique names. This also goes for the "labels" of the may not have empty (null) labels for any of the devices or the SmartApp will crash.
  • If you change any settings within you app (add/remove devices to the SmartApp, add/change modes or routines), you will need to get the proper "intents" and paste those into the Amazon Developer Site. See Ask_Alexa#Custom_Slot_Information for more information.
  • The longer your modes or routines are in length, the more likely Alexa will misunderstand what you are asking. Amazon recommends commands of less than three words or syllables.
  • By default, SmartThings adds exclamations points to is routines (for example, "Good Morning!") . While the Ask Alexa SmartApp attempts to reconcile this when evaluating what the Alexa hears, it is best practice to remove punctuation from your routines or modes.
  • Try speaking different ways to Alexa to get the results you want. For example, if you'd rather say the device action first, just append "using SmartThings" at the end to get the same result. For example, instead of <"Alexa, ask SmartThings to turn on the living room"> you could say <"Alexa, turn on living room with SmartThings">. Please note that sometimes this doesn't work well depending on what you named the device or how the Alexa Enabled Device hears your commands. However, it is important to be creative in how you address Alexa. If you find that natural speech doesn't work and have a suggestion for another syntax for different types of devices, please contact the author of this app to have additional utterances created.


The following are common troubleshooting steps when working with Ask Alexa.

  • If you use 'smartthings' (one word) as you invocation for the skill and you find Alexa misunderstanding you and not initiating the skill, change the invocation word to 'smart things' (two words) as some users have found this to work considerably better.
  • There have been reports that sometimes the URL for the Setup Variables presented in the live logging will not show completely, with a portion of it being replaced with [TRUNCATED]. This is an issue with the SmartThings environment. If you encounter this, within your mobile device scroll down on the Setup Variables page. You will find the full address of the setup page. Copy this and send it (possibly via e-mail) to yourself so you can perform the setup actions using a desktop computer.


  • If you see an error similar to below about a mode or routine being missing, this indicates you may have deleted one of these before removing it from Ask Alexa. To prevent issues, the list will be updated to indicate which modes or routines you need to remove from the list for proper operation. You may also see this situation when you delete an Echo device association with a room. The list presented will mark the missing device, and it should be removed from the list to ensure proper Ask Alexa operation.


  • If you can use the Amazon Developer simulator with Ask Alexa, but you get an error with the exact same command with voice, check your country selection in both the app and the developer's site. These should match and only US is supported (However, it appears UK DOES work).
  • When the application does not operate correctly or as you would expect, please check to ensure the SmartThings environment is working properly. If the SmartApp suddenly stops working, most of the time it is because of an outage or degraded service with SmartThings' cloud environment. Since Ask Alexa is also heavily based in the Amazon cloud environment, it is also recommended to check the status of those sites as well via
  • There is a known issue where, after editing a macro, the application returns to the main SmartThings app instead of the Ask Alexa main interface. SmartThings is aware of this and is working on a resolution. This message will be removed when this issues is resolved.
  • Removal and renaming of internal SmartThings items (like modes and routines) or changing internal components to Ask Alexa (such as deleting macros, or renaming extensions) is not well supported in SmartThings. For example, if you have a SmartThings mode that is used in Ask Alexa, deleting this from the SmartThings app BEFORE removing it from Ask Alexa could result in Ask Alexa getting confused and giving you an error is the GUI or during operation. Another observed behavior is when you have a weather report within voice report. If you plan to delete the weather report, you should remove it from all areas of the app before deleting it.
  • While it is expected that you can upgrade to new versions seamlessly, there are situations where internal variables within the code changes or an old scenario conflicts with new code revisions. If you upgrade and find the application no longer performs as expected, it is recommended that you remove the application completely and start from scratch with new code (this only applies to the code in SmartThings. The Lambda code and Skills data should not be affected by variables unless you change your devices).
  • If you receive an error in the app while working with routines, macros and devices, please be sure these items do not have commas, exclamation points, or apostrophes in them. Also, numeric values (1, 2, 3, etc) should be left out in most circumstances from devices and macros. In addition, ensure you have not inadvertently created a 'null' routine...this is a routine you may have attempted to create but abandoned. These will show up in your SmartThings IDE under you Installed SmartApps. If this happens, simply delete the routine via the IDE (<<My Locations>>, <<List SmartApps>>) by tapping <<Edit>> in the upper left corner and the <<Update>> commands will turn into <<Delete>>.


  • When naming your macros, routines, aliases, devices or modes, ensure you don't use words that might sound the same but could be spelled differently. For example, "Kris", "Bryan", "Jon" could be heard as "Chris", "Brian" and "John", respectively. Unfortunately, while sounding the same, the app does not account for different spellings of these types of names. Therefore, it is recommended you stay away from words like this. If you must use these, it is recommended that you set up aliases with different spellings of the same name.
  • When making a change to your environment (add/remove devices/aliases, create new modes, etc.) you should go through the setup steps again to capture any new custom slot information. This is required so Ask Alexa and the Amazon developer site knows the 'nouns' and 'verbs' to use to process your requests.
  • As mentioned in the Ask_Alexa#Tips_and_Tricks section, naming (labels) of your devices are rather important. In addition, even if you name everything uniquely, there are still areas where Alexa will respond with "You have multiple devices that are named <device name> in your SmartThings SmartApp. Please rename these items to something unique so I may properly utlize them.". This could be caused by you choosing the same device for different functions. For example, you can choose a thermostat (Let's say "office") and also choose it for your temperature reading or humidity sensor. This will cause an issue as Alexa has no way of understanding the context of a device that is listed multiple times. It is best practice to not only name you devices uniquely, but use them once within your device setup. For situations where you can't name devices differently, you can use the alias function(see Ask_Alexa#Allow_Device_Aliases) to utilize different names for the devices in your SmartThings account.
  • If you receive an error similar to this when attempting to add a new extension (like a message queue):


This indicates you have not put the extension code into your SmartThings IDE. Please follow the direction here Ask_Alexa#Ask_Alexa_Extension_Code_Installation to resolve this issue.

  • If you receive feedback that SmartThing SmartApp returned an error, but you see nothing in your IDE Live Logging, you may have an issue with your Application ID or Authentication token. Re-run the setup to get the proper information into your Lambda code. (See Ask_Alexa#Finalizing_The_Function_Code)
  • If you are unable to find the Alexa Skill Kit when setting up the Event Triggers (Ask_Alexa#Configure_Triggers), be sure you have set up your account in one of the supported datacenters (i.e US East (N Virginia), US West (Oregon), etc (see Ask_Alexa#AWS.2FLamba_Code)
  • If you find behavior that is not what you would expect from your devices, try changing your syntax of how you are referencing the device. For example, instead of <"Alexa, tell SmartThings to turn on the Kitchen"> try a simplistic version such as <"Alexa, tell SmartThings Kitchen on">. If you find a specific syntax works better for you but is not being recognized, you may want to create (or ask for community assistance) a custom utterance for your situation. If it works well for you, you can submit that to the author of Ask Alexa for inclusion in future updates.
  • If you have a custom message (or a pre or post message within the voice report macro) it is recommended to use proper punctuation. This means to end the message with a period, question mark, or exclamation point. This will ensure Alexa pauses if you have a continuing message at the end of your macros.
  • While the Lambda accounts are "free" for the most part, you should monitor your usage as much as you can to ensure you know the volume of calls being made to your account. Amazon has some fantastic tools to accomplish this via the main dashboard of your AWS account. The dashboard can also be useful in troubleshooting errors within your application.


  • If you get the error "There was an error with the requested skills response" from Alexa but the action still happens, what may be happening is that the response was taking too long to get back from SmartThings to the Amazon Lambda code. To help reduce these errors, go to your Lambda code at Amazon AWS site and find section toward the bottom of the page labeled <<Basic Settings>>.Change the <<Timeout>> section to a larger number (6 to 20 seconds should be more than enough time). You can also increase the amount of memory that your Lambda code uses. This MAY result in slightly faster response from the Ask Alexa skill; however, increasing the timing or memory too much could result in a monthly charge from Amazon. If you do increase these settings, be sure to monitor your usage closely through the Amazon tools.


  • Ask Alexa keys off the labels of the devices; these are what you use to address the device. If these labels are not unique or used multiple time within the SmartApp you will receive a warning at the top of the main interface page.


To fix a multiple device issue, be sure to examine all of the main interface devices to ensure they are not used more than once. For example, a dimmer can also be a switch, and a motion sensor may also show up in a temperature listing.

For null device labels, be sure to check the device within the IDE area <<My Devices>> to ensure the label is not blank.


To obtain support for this app, you have a couple of options:

  • A Slack channel has been set up at . You must be invited to this app and have a Slack account. This will allow real time conversation and troubleshooting with the developer to get to the bottom of any issues you might be having.
  • For general questions about the app, please visit the official forum for this app on the SmartThings Community Page:


There are many things that can be added to this application. Be sure the visit the forum for this app (See above) for this app to request something be added to the road map. In addition, donations will help speed up development of new features. You can donate via this page: . Please note that these are only proposed updates...There is currently no timeline to implement these, or any guarantee that they will be implemented at all.

  •  % control for window shades
  • Continue to improve the setup process (started in 2.3.5a)
  • Restrictions based on which speaker is being spoken to (2.3.9)

Frequently Asked Questions (FAQs)

Question: Why do I have to update the Developer JSON every time I change something in my app?

Answer: The framework of the app allows for great voice recognition as only items that you set up in your SmartApp are being scanned for. Technically, you could simply have every device in your environment from the beginnig. However, that increases the chance of a misunderstanding by Alexa.

Question: What colors does Ask Alexa support?

Answer: Ask Alexa supports all of the same colors supported by native SmartThings app: Soft White, Warm White, Daylight White, Cool White, White, Alice Blue, Antique White, Aqua, Aquamarine, Azure, Beige, Bisque, Blanched Almond, Blue, Blue Violet, Brown, Burly Wood, Cadet Blue, Chartreuse, Chocolate, Coral, Corn Flower Blue, Corn Silk, Crimson, Cyan, Dark Blue, Dark Cyan, Dark Golden Rod, Dark Gray, Dark Green, Dark Khaki, Dark Magenta, Dark Olive Green, Dark Orange, Dark Orchid, Dark Red, Dark Salmon, Dark Sea Green, Dark Slate Blue, Dark Slate Gray, Dark Turquoise, Dark Violet, Deep Pink, Deep Sky Blue, Dim Gray, Dodger Blue, Fire Brick, Floral White, Forest Green, Fuchsia, Gainsboro, Ghost White, Gold, Golden Rod, Gray, Green, Green Yellow, Honeydew, Hot Pink, Indian Red, Indigo, Ivory, Khaki, Lavender, Lavender Blush, Lawn Green, Lemon Chiffon, Light Blue, Light Coral, Light Cyan, Light Golden Rod Yellow, Light Gray, Light Green, Light Pink, Light Salmon, Light Sea Green, Light Sky Blue, Light Slate Gray, Light Steel Blue, Light Yellow, Lime, Lime Green, Linen, Maroon, Medium Aquamarine, Medium Blue, Medium Orchid, Medium Purple, Medium Sea Green, Medium Slate Blue, Medium Spring Green, Medium Turquoise, Medium Violet Red, Midnight Blue, Mint Cream, Misty Rose, Moccasin, Navajo White, Navy, Old Lace, Olive, Olive Drab, Orange, Orange Red, Orchid, Pale Golden Rod, Pale Green, Pale Turquoise, Pale Violet Red, Papaya Whip, Peach Puff, Peru, Pink, Plum, Powder Blue, Purple, Red, Rosy Brown, Royal Blue, Saddle Brown, Salmon, Sandy Brown, Sea Green, Sea Shell, Sienna, Silver, Sky Blue, Slate Blue, Slate Gray, Snow, Spring Green, Steel Blue, Tan, Teal, Thistle, Tomato, Turquoise, Violet, Wheat, White Smoke, Yellow and Yellow Green

How Do I Upgrade Ask Alexa

There are 3 different scenarios for upgrading Ask Alexa; each depends on what was changed in the release. Please refer to the release notes to determine which scenario applies to your situation. For a scenario 2 and 3 upgrade, you should be familiar with the installation processes for the Amazon sites listed here: Ask_Alexa#Developer_and_Lambda_Code_Installation

Scenario 1 - IDE code change: Only the code (either main code, or extension code) has changed. If you have your IDE linked to GitHub (see: Ask_Alexa#Advanced_Installation), then you simply click the <<Update from Repo>> button at the top of the SmartThings IDE and check the apps that you want to update. Be sure to <<Save>> the files and <<Publish>> them in order to see the changes in your SmartThings mobile application.

In addition, in a Scenario 1 installation you can also upgrade the applications using the Community Installer (Free Marketplace). See here for more information: Community_Installer_(Free_Marketplace)

Scenario 2 - Lambda code change: It is rare that JUST the Lambda code will change. Sometime you must use the processes in Scenario 1 and this process to get the full upgrade. There are two ways to upgrade your Lambda code. Both require you to go to <<Settings>> <<Setup Variables>> and get your setup URL.


Scenario 3 - Developer area changes: The easiest method of upgrading is to go to <<Settings>><<Setup Ask Alexa>><<Display Setup Variables Link>> and get your setup URL. While displaying this on a PC, you will simply click the Developer code link (or download the code). If you display the code, copy the entire page of JSON code and then paste it to the <<JSON Editor>> section of the Developer Build section.


If you downloaded the code, simply upload the code to the site.


Save and build your interaction model and you are complete.