Ask Alexa - Message Queues

The Unofficial SmartThings Blog
Jump to: navigation, search

The Message Queues are an extension to Ask Alexa, the popular SmartThings Add in. You must be running Ask Alexa to use Message Queue. More information about Ask Alexa can be found here: Ask Alexa

The message queues are a holding area for external messages that may come in from other SmartApps. Unfortunately, Alexa Enabled Devices can't wake with anything other than voice (or button push) yet, so alerting in real time using these devices is impossible. However, the message queue can hold these alerts or message and they can be played back (i.e. <"Alexa, tell SmartThings to play {message queue name} Messages">). If you DO need real time notifications, you also have the option of sending the notification to an external speaker or synth device.

Summary

Mailbox.png

Category: Ask Alexa Extension - Requires Ask Alexa

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

ST Community handle: https://community.smartthings.com/users/michaels/activity

Latest Version

The latest version this extension (as of 3/16/18)
Ask Alexa Extensions Area Used Version Location
Message Queue Code SmartThings IDE 1.0.8 https://github.com/MichaelStruck/SmartThingsPublic/blob/master/smartapps/michaelstruck/ask-alexa-message-queue.src/ask-alexa-message-queue.groovy

Ask Alexa Extension Code Installation

To install the extension use the code located here:

   https://github.com/MichaelStruck/SmartThingsPublic/blob/master/smartapps/michaelstruck/ask-alexa-message-queue.src/ask-alexa-message-queue.groovy

The steps for installation of the extensions 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.

Message Queue Options

These options will enable you to configure the Ask Alexa Message Queue. These options are global to all message queues. In other words, these settings apply to all message queues (primary and the ones you create).

AAMQOptions.png

Message Queues Displayed On Main Menu

Since messages that in the queue may be important (locks unlocked, water present), you have the ability to turn on a notification on the Ask Alexa main menu allowing you to know when messages are present and are able to view the messages without being near the Alexa device. You can also delete these messages from your message queue using the user interface.

MQMain.png

External SmartApps Delete Message Queues

Depending on the SmartApp, there may be a need to delete message from the queue (i.e. expired messages, updates to messages, etc). Enabling the <<Allow External SmartApps To Delete Message From These Queues>> option will allow those SmartApps to delete messages from the queue. Please refer to the instructions of the sending SmartApp (see: Ask_Alexa_-_Message_Queues#Delete_Messages_In_Message_Queue) to determine if you need this option enabled.

Append Alexa Output With Message Notification

When you choose Message Queues in the <<Append Alexa Output With Message Notification From These Queues>> area, a message will be appended to the Alexa output every time you use the device. For example, the conversation flow with your Alexa might be like this:

   You: "Alexa, tell SmartThings to turn off Kitchen"
   Alexa: "I have turned off the kitchen. Please note: You have messages present in
   the following message queues: Primary Message Queue and John's room"

If you choose not to append your messages with these notifications, you may still query the Alexa connected device to find out if you have messages. The syntax is simply <"Alexa, Ask SmartThings about {message queue name}"> You many alse delete the messages using the syntax (<"Alexa, tell SmartThings to erase {message queue name} Messages"> or <"Alexa, tell SmartThings to delete the {message queue name} Messages"> ).

Forward Messages From Primary Queue

To support legacy applications that do not yet support the message queue extensions, the <<Forward Messages From Primary Message Queue To>> option will give you a selection of message queues to forward messages to. This setting is universal; all messages received by the primary message queue will be forwarded to queue you choose regardless of their source. When you view your message queue on the main menu, or when you play the messages from your Alexa Connected Device, the message will be appended with a note that it was forwarded from the primary message queue.

This option will eventually be deprecated as partner developers migrate to the newest message queue structure.

Primary Message Queue

The Primary Message Queue is the default mail box (and can not be deleted) and provides external partners' SmartApps an area to send messages to if they do not yet support the message queue extensions. Prior to version 2.2.4, there was only one message queue; now, the user can configure multiple message queues. Most developers have committed to supporting this new structure.

   Please Note
   It is estimated before 3.0.0 the primary message queue will be deprecated. 
   It is recommended you create your own message queues instead of using primary 
   message queue. Current versions of Ask Alexa provide a forwarding function 
   (see: Ask_Alexa_-_Message_Queues#Forward_Messages_From_Primary_Queue) to intercept primary message 
   queue messages and re-directed them to another queue. This function will also deprecate, 
   but may lag the primary message queue deprecation by a few versions.

The options on this primary message queue are identical to the options you can set for the message queues you create.

AAMsgQueue.png

You can choose how the messages are played back (oldest to newest, or newest to oldest) on the Alexa Connected Device. This setting is also applicable to how they are displayed on the main screen if you choose this option (see: Ask_Alexa_-_Message_Queues#Message_Queues_Displayed_On_Main_Menu).

If you need real-time alerting to notifications, you have a few options. See Ask_Alexa_-_Message_Queues#Message_Notification_Options for these notification options.

In each of the notification areas, you can choose to implement restrictions (global to the queue you are creating) to have times of day, presences, days of week, mode or which switches are on or off to determine if notification happens when a message arrives (the message will always be delivered to the message queue even if notifications are restricted).

Additional Message Queues

You will create new message queues similar to how new macros are created. Find the green button labeled <<Create A New Message Queue...>>

AANewMQ.png

As you create message queues, you will be required to enter a name for the message queue, along with different options for message playback and message notification, whether it be a light going on/off, a speaker/synth device notification, or an SMS/Push notification.

   Notice
   As mentioned a number of times, when naming your message queues, ensure your
   message queue names are unique not only within the context of the other queues, but 
   within the parent app itself. That means a message queue 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.

If you receive an error similar to this when attempting to create new message queue:

AAMQError.png

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

Message Notification Options

When a message arrives within one of the message queues there are various methods you can use to either hear the message in real-time, or be alerted a message is waiting for you in the message queue.

Audio Notification

When you click the area labeled <<Message notification - Audio>> an additional set of options for output devices (speaker or synth device) will appear. When choosing this notification option, you have the choice to play the full message on the speaker, synth device or to just a notification that there is an incoming message. No matter what option you choose, your message will always be waiting on the Alexa Connected device if you simply say <"Alexa, tell SmartThings to play primary messages">. If you choose to output to a speaker (like Sonos), you also have the ability to choose the voice that will be output during a message.

   Please Note
   Messages going directly to Alexa devices using TTS need to utilize applications
   such as Echo Speaker or Echo Speaks (http://thingsthataresmart.wiki/index.php?title=Echo_Speaks). 
   Each of these applications allow you to setup your Alexa devices as SmartThings TTS
   speakers. Please note that Echo Speaks utilizes different programming commands, 
   so if you choose devices from this be sure to check the "Echo Speaks" toggle when 
   selecting the speakers.

Visual Notification

You can have a visual notification of a message in the message queue via an on/off light or colored light that turns on when there is a message waiting. Simply choose a light switch from the <<Turn On Lights When Messages Present>> or <<Turn On/Set Colored Lights When Messages Present>> selection areas. If you use a light to indicate a message is waiting, you also have an option to turn off the lights when the queue has been emptied (either by you or by a partner SmartApp).

Mobile Notification

If you want to be notified of a message on your mobile phone, you can choose the options in the <<Message notification - Mobile>> area.

   Notice
   Newer versions of the SmartThings Mobile App will allow you to set up specific 
   contacts to push or send SMS messages to. The app automatically detects when
   you have the Contacts page available to you and will be the preferred method
   of contact when enabled.
   
   Also Note 
   It has been advised by SmartThings to NOT excessively use the SMS functionality
   of the app. While it is fine for general notifications as you would do with the
   other aspects of SmartThings Mobile App, DO NOT use Ask Alexa as a way to text 
   friends and family for recreation; doing so may require SmartThings to disable
   or limit this functionality in the future. If you need to generate excessive
   notification traffic, please use the push functionality.

Reminder About Amazon Developer Slots

Please remember ANY changes or additions you make to your Ask Alexa environment should immediately be followed up with running <<Settings>> <<Setup Variables>> in the main Ask Alexa SmartApp. This will allow newly created message queues to be reflected in the Amazon developer site. See Ask_Alexa#Setup_Variables for more information.

Message Delivery

Please note that while message delivery using the 'sendLocationEvent' is rather consistent, this is a non-standard way to exchange information between SmartApps...If your app sends out multiple messages per second, there is a possibility that the message may not be processed by Ask Alexa. It is recommended you meter the speed at which messages are sent to the queue while a message verification system is being developed.

Advanced: Interfacing With Ask Alexa (Developers)

Within the SmartThings environment, each SmartApp runs independently from each other. For example, Ask Alexa can not interfere with CoRE, or vis-versa. However, the drawback of this is that SmartApps can not work together in normal circumstances. However, there are ways for SmartApps to share information using the SmartThings location events. This is how CoRE, for example, knows the names of the Ask Alexa Macros, or knows when a macro has run.

With the implementation of the Message Queues in Ask Alexa, a standard method of sending messages to Ask Alexa is required. The SmartThings location events will serve this purpose. If you are a developer of a SmartApp and wish to send messages to the Ask Alexa Message Queue you will need to conform your output to the follow standards.

Currently, the following community apps [1] support or plan to support the message queue (items with (2.0) in them can utilize the user-created message queues).

Send Messages To Ask Alexa

There are two required steps in order to interface with Ask Alexa's message queues:

  • First, you must subscribe to the askAlexaMQ location event. This will feed your app a list of available message queues within Ask Alexa. The formatting of this command is simple:
subscribe(location, "askAlexaMQ", askAlexaMQHandler)

The location information you receive back will have a data field with the list of queues available. It is recommended you place these in a state variable like this:

    
def askAlexaMQHandler(evt) {
   if (!evt) return
      switch (evt.value) {
         case "refresh":
            state.askAlexaMQ = evt.jsonData && evt.jsonData?.queues ? evt.jsonData.queues : []
            break
      }
}

Please note the queues listing will be a data map with the ID and the name of the queue.

  • Second, with the information above, you will typically deliver an option to the end user with a list of where to send the output. You can do with with an "enum" input like this:
input "listOfMQs", "enum", title: "This is a list of the Ask Alexa Message Queues", options: state.askAlexaMQ, multiple: true, required: false

Then, when you are ready to trigger the output you will use a sendLocationEvent() with the follow parameters:

sendLocationEvent(
    name: "AskAlexaMsgQueue", 
    value: "MySmartApp", 
    isStateChange: true, 
    descriptionText: "This is the message I am sending to Ask Alexa", 
    unit: "######", 
    data:[
        queues:[ID1,ID2...],
        overwrite: true*,
        expires: seconds**,
        notifyOnly: true*,
        suppressTimeDate: true*,
        trackDelete: true*
    ]
)

*='overwrite','suppressTimeDate', 'notifyOnly' and 'trackDelete' default to 'false' if these parameters are not used
**=Having no value in this field means the system will keep the message in the queue until deleted by the 
   user or in bulk by the sending application

As seen here in the SmartThings documentation [2], there are many parameters you can use when logging a Location Event (using sendLocationEvent()). Ask Alexa uses these:

Parameter Information
name This is the key that Ask Alexa subscribes to. This MUST be AskAlexaMsgQueue
value This is the (sending SmartApp) name that be spoken as part of the Message Queue voice message.
descriptionText This is the message you wish to have Alexa play.
isStateChange This must be set to TRUE
unit This parameter is OPTIONAL for sending message to the message queue, but REQUIRED if you ever want your app to delete messages from the queue. Setting 'unit' provides additional security by allowing sending apps to delete specific messages from the message queue, either in bulk, or by individual message. It is the responsibility of the sending app to keep track and organize their ID (unit) naming structure so that other applications don't accidentally delete their messages within the queue. This can be any STRING designated by the sending app.
data This field allows for future expansion. See below for the current labels/tags.


Data field items
Data Label How used
queues This is a map of the message queues that should accept the messages. Please note that these will be either the message queue AppID or "Primary Message Queue". It is recommended you obtain the map from the list sent by Ask Alexa
overwrite "true" or "false" (lower case). Defaults to "false" if no value is given. This is similar to the message queue delete function (see Ask_Alexa#Delete_Messages_In_Message_Queue in that it requires the value and unit fields to be populated. In addition, the user must still enable the ability for smartapps to delete messages. This function is perfect for applications that send multiple entries (like a door opening or closing) but only the latest value is relevant.
expires This is the number of seconds from when the message is received that it will automatically remove itself from the message queue. It is recommended that you give the user the option to enter a number in minutes, then multiple this number by 60 to send Ask Alexa the number of seconds.
notifyOnly "true" or "false" (lower case). Defaults to "false" if no value is given. This value will allow applications to only notify (based on the user's notification settings) to a message an NOT place it into the message queue. It is up to the user to ensure that notifications (Visual, Audio or Mobile) are enabled as the message will be be saved if no notification options are enabled. This option is good for real-time alerting (such as weather advisories) that are not relevant even moments after the message is sent
suppressTimeDate "true" or "false" (lower case). Defaults to "false" if no value is given. This value will allow applications to suppress the time and date playback when listening to messages from the queue on the Alexa. Users have the option to suppress this information on a global queue basis; this option allows for the suppression to be on a per-message basis. This is useful for smartapps that embed their own time date information into the messages. For example, "The bedroom light was turned on at 4:45pm on Tuesday"...it would be a little redundant to have a header that also told the time and date.
trackDelete "true" or "false" (lower case). Defaults to "false" if no value is given. This value will allow applications to be sent a sendLocationEvent (value = messageValue.messageUnit) when the message expires or is deleted by the user.

Receiving Message

To receive these messages, Ask Alexa subscribes to the location event like this:

subscribe(location, "AskAlexaMsgQueue", msgHandler)

The message, once received, is placed into a state variable within the application. Since Alexa can not wake on alerts (see Ask_Alexa#Limitations), the alerts are kept in this variable until the user initiates a command using Ask Alexa. When the action requested is completed, the user is alerted to the pending message(s), giving them the option to play the messages.

At this time, there is no scheduling function for these notes. In other words, the sending app is responsible for delivering messages to Ask Alexa, and the date stamp is dependent on the order in which they are received. The user has the option to play oldest first, or newest first (default it oldest first).

   Please Note
   In a multi-room setup (see Ask_Alexa#Multi-Room_Controls_.28Advanced.29), the messages
   will still go to each instance of the app you have set up. This will change as Ask Alexa 
   is further developed and Amazon opens up the 'push' notification function.

Delete Messages In Message Queue

The message queue is very flexible in how it can be used; however, with anything voice related it is always important to balance between information relevance and quantity. For example, if you have an app that alerts (sends messages to the queue) of a non-critical nature (maybe some sort of information only message), it may not be important for the user to hear all of the messages if the original alert/notification has subsequently cleared. As such, using both the value and unit parameters, a developer can issue a sendLocationEvent() that will allow an external app to selectively delete messages that may have sent to the Ask Alexa queue previously. For this option to work, the end user must enable the queue to allow for deletions (see Ask_Alexa#External_SmartApps_Delete_Message_Queues)

   Please Note:
   You must use send the unit and value parameter when sending the original message
   to successfully delete messages from the message queue. This is to prevent 
   one app from deleting another app's messages when the same application name (value) is used. 
   You will be UNABLE to delete any message from the queue if the unit parameter is missing. 
   As such, your unit parameter should be unique. Depending on your needs, this unit 
   parameter can be unique to every messages (allowing individual messages to be deleted), or the 
   same for every message and the sending app, allowing ALL messages with that unique identifier 
   to be deleted in bulk. 

To issue a delete command to the message queue, use the following parameters:

name This is the key that Ask Alexa subscribes to. This MUST be AskAlexaMsgQueueDelete
value This is the (sending SmartApp) name. This value must match the original message(s) that you are attempting to delete.
isStateChange This must be set to TRUE
unit This parameter is REQUIRED for a delete. This is a string value and MUST match the message(s) you want to delete. As mentioned above, to delete messages in bulk, simply use a unit parameter that is linked to the value parameter. Or, individual messages can be selectively deleted by having the unit parameter unique to each message sent from the app.
data This field allows for future expansion. Currently, it is used to send a map of message queues IDs/Labels to partner applications.

Putting this together, the syntax within your SmartApp would look like this:

sendLocationEvent(
    name: "AskAlexaMsgQueueDelete", 
    value: "MySmartApp", 
    isStateChange: true, 
    unit: "######", 
    data:[
        queues:[ID1,ID2...]
    ]
)

Currently, there are no "wildcard" searches for the unit parameter. To delete multiple messages, separate sendLocationEvent() commands should be sent for every unique unit parameter.

Refresh Message Queue List

For developers that may want to install and app and immediately refresh the list of message queues available (instead of going out of the newly installed app and then going into Ask Alexa, then back into the the app, you can call the following command:

sendLocationEvent(
    name: "AskAlexaMQRefresh", 
    isStateChange: true 
)

The list will be rebroadcast as mentioned above using the "askAlexaMQ.refresh" event value.

Track Deletion Of Messages

If your app needs to know if a message you sent has been deleted, you must first tag you message. You do this in the "data" field by setting the "trackDelete" to "true" (see Ask_Alexa_-_Message_Queues#Send_Messages_To_Ask_Alexa)

Next, you app should already be subscribed to the "askAlexaMQ" location event:

subscribe(location, "askAlexaMQ", askAlexaMQHandler)

At the method "askAlexaMQHandler(evt)", you will look for the evt.value of the your original message's app name (value) and message id (unit) combined with a period between them.

For example, if your a is "MyApp" and your message id is 1234, you will look for this combination

def askAlexaMQHandler(evt){
    if (evt.value == "MyApp.1234") {
        <Event to occur when your message is deleted>
    }
}

If you need to know if the deletion of the message was a clearing of the queue (user invoked), an app deletion (usually through an overwrite or when your app deletes a message), or through expiration of a message, the data field delivered with the askAlexMQ event will include the following JSON fields:

  • deleteType: "delete", "delete all" or "expire"
  • queues: The message queue name where the message was removed from