Customize Multimodal Devices for Alexa Smart Properties


In Alexa Smart Properties, you can complement the voice experience with visual content rendered on Alexa-enabled multimodal devices. Take advantage of the home screen to share details of the property, enable service ordering with voice or tap, and inform guests about events, updates, and skills.

You can add visuals to your property skill that Alexa displays when the guest interacts with a multimodal device by voice or tap. For example, when a guest asks, "Alexa, what time is breakfast?" you can display the hours, location, and breakfast menu. And, you can add visuals that Alexa displays when the guest isn't interacting with the device. For example, add images and visual messages to inform guests about upcoming events or the location of places on the property.

Follow these guidelines to send visuals from your property skill or property management application.

Supported devices

You can use the following multimodal Amazon Echo devices with Alexa Smart Properties:

  • Amazon Echo Show 5 (1st, 2nd, 3rd Generation)
  • Amazon Echo Show 8 (1st, 2nd, 3rd Generation)
  • Amazon Echo Show 15

Recommendations

If you have multimodal devices on your property, Amazon recommends that you customize the home screen with the following visuals:

  • Send a visual response with each voice response from your property skill by using Alexa Presentation Language (APL).
  • Make sure that you define the device address correctly to enable Alexa to display the default weather card based on the location of the property. To update the address of an Alexa-enabled device, use the POST address setting API.
  • Provide at least seven proactive suggestions to display when guests aren't interacting with the device. Alexa displays each suggestion in a rotating fashion. The suggestions should include the following information:
    • Three suggestions for Alexa features, such as how to change volume.
    • Four suggestions for property features, such as how to connect to Wi-Fi or restaurant hours.
  • Use persistent visual alerts to display visual information that stays on the device.

Add visual responses from your skill

You can complement the voice responses from your property skill with visual responses that give more information, let the guest tap to select options, display images of the property, and more. For example, if the guest asks when the restaurant opens, your skill can give the answer with voice, and also display the restaurant hours for the day.

You can send visual responses from your skill by using APL, a responsive layout language that lets you build visuals to render on Alexa-enabled multimodal devices. To create visual responses with less effort, you can use the APL responsive components and templates instead of building your own layouts. With responsive components and templates, you choose the template and populate the data that you want to display. For details about how to add visual responses to your skill code, see Add APL Support to Your Skill.

The following table shows recommended APL templates suited for property skills.

APL template Example uses Sample utterances

Headline

Use to display a short, centered message with a background image, such as the property welcome screen.

"Alexa, open property skill name."

Image list

Use to display a scrolling list of images and text, such as the following responses:

  • List of dishes and drinks available at the restaurant.
  • List of services available on the property.
  • Search results.

"Alexa, recommend a place to eat."

Text list

Use to display a scrolling list of test-based items, with an optional header and background image, such as the menu items. Use this template when you don't have images for each item on the list.

"Alexa, what's for breakfast?"

Detail

Use to display text and an image to present structured information about a service of a property, such as service name, operating hours, location, and description.

"Alexa, is the gift shop open?"

Karaoke

Use this template when none of the other templates apply, usually for long-form text of more than two lines that scrolls automatically. You can display the same text that Alexa speaks on the screen.

"Alexa, how do I connect to Wi-Fi?"

Send proactive suggestions

You can use proactive suggestions to display visual content on Alexa-enabled multimodal devices to inform guests about your property, such as events, services, and amenities. Alexa renders these suggestions as cards on the home screen. When not responding to guest queries, Alexa rotates through the cards and displays the most recent suggestion first.

Customize the visual content for your property and send the suggestions on a time schedule. This content should be a mix of Alexa-submitted cards that tell the guest how to use Alexa features and developer-submitted cards that display information about the property. Proactive suggestions are great for content that isn't urgent, such as property information and events, weather, and news. Also, display information that's helpful to the guest, such as how to connect their mobile device to Alexa or how to connect to the property Wi-Fi.

To add a card to the home screen rotation, use the Proactive Suggestion REST API to create a campaign for a list of units. For each campaign, include the content to display on the screen. The API provides a set of templates you can choose from to display your content. For details the templates, see Campaign templates. You create one campaign for each suggestion that you send. Each template supports including a background image.

Alternatively, you can use the Alexa Smart Properties Console to create proactive suggestions. For details, see Manage Content in the Management Console.

The persistent proactive suggestion templates support background images. For details about images, see Background images for proactive suggestions and visual alerts.

The following example uses the Text wrapping template to show a card that explains how to set up a timer.

Copied to clipboard.

POST /v1/proactive/campaigns HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {access token}
{
  "suggestion": {
    "variants": [
      {
        "placement": {
          "channel": "HOME"
        },
        "content": {
          "values": [
            {
              "locale": "en-US",
              "document": {
                "type": "Link",
                "src": "doc://alexa/apl/documents/home/cards/textWrapping"
              },
              "datasources": {
                "displayText": {
                  "primaryText": "Need to set a timer?",
                  "secondaryText": "Try: \"{WakeWord}, set a timer for ten minutes.\""
                },
                "background": {
                  "backgroundImageSource": "https://www.example.com/image.jpg"
                }
              }
            }
          ]
        }
      }
    ]
  },
  "targeting": {
    "type": "UNITS",
    "values": [
      {
        "id": "amzn1.alexa.unit.did.unitId1"
      }
    ]
  },
  "scheduling": {
    "activationWindow": {
      "end": "2022-12-31T00:00:00.00Z"
    }
  }
}

Example proactive suggestions

The following table shows example suggestions that you might display to your guests.

Type of suggestion Primary text Secondary text

Alarm

Need to set a wake-up call?

Try "Alexa, set an alarm for 6:00 AM."

Timer

Need to set a timer?

Try "Alexa, set a timer for 10 minutes."

Entertainment

Listen to music with Alexa

Try "Alexa, play music."

Entertainment

Listen to your favorite music genre with Alexa

Try "Alexa, play jazz."

Entertainment

Listen to the radio with Alexa

Try "Alexa, play radio 1."

Entertainment

Looking for something to watch?

Try "Alexa, what's on TV tonight?"

News

Looking for a Flash Briefing?

Try "Alexa, play the news."

Communications

Need to talk to guest services?

Try "Alexa, call reception."

Smart home

Want to adjust your room temperature?

Try "Alexa, set the thermostat to 70 degrees."

Smart home

Control your curtains by voice

Try "Alexa, close the curtains."

Property-specific welcome

Hello, I'm Alexa

Try "Alexa, what can you do?"

Property-specific welcome

You're in Property Name

Try "Alexa, tell me more about the property."

Property information

Need to connect to Wi-Fi?

Try "Alexa, how do I connect to Wi-Fi?"

Property information

Checkout time is 11:00 AM

Try "Alexa, can I extend my stay?"

Property services

Need room cleaning?

Try "Alexa, clean my room."

Property services

Discover the morning specials

Try "Alexa, what's for breakfast?"

Property services

Need a ride?

Try "Alexa, order a taxi."

Property assistance

Need help?

Try "Alexa, I need assistance."

Send persistent visual alerts

Persistent visual alerts are similar to proactive suggestions except the card stays on the screen until the expiration time or the guest dismisses the alert. Use persistent visual alerts for upcoming events, appointments, and other information that's important for the guest to see. You can set a separate alert for every booking or appointment that the guest makes by voice or tap.

To publish persistent visual alerts, use the Notifications API and include the content to display, along with an expiration time. The API provides a set of templates you can choose from to display your alert. For details the templates, see Persistent visual alert templates.

Alternatively, you can use the Alexa Smart Properties Console to create persistent visual alerts. For details, see Manage Content in the Management Console.

The persistent visual alert templates support background images. For details about images, see Background images for proactive suggestions and visual alerts.

The following example shows a visual alert that uses the Text wrapping template to remind the guest to take a walk.

Copied to clipboard.

POST /v3/notifications HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {access token}
{
    "recipients": [{
            "type": "Unit",
            "id": "amzn1.alexa.unit.did.unitId1"
        },
        {
            "type": "Unit",
            "id": "amzn1.alexa.unit.did.unitId2"
        }
    ],
    "notification": {
        "variants": [{
            "type": "PersistentVisualAlert",
            "content": {
                "variants": [{
                    "type": "V0Template",
                    "values": [{
                        "locale": "en-US",
                        "document": {
                            "type": "Link",
                            "src": "doc://alexa/apl/documents/enterprise/notifications/persistentvisualalert/textWrappingTemplate"
                        },
                        "datasources": {
                            "displayText": {
                                "primaryText": "Exercise Reminder",
                                "secondaryText": "Time to take a walk!"
                            },
                            "background": {
                                "backgroundImageSource": "https://www.example.com/image.jpg"
                            }
                        }
                    }]
                }]
            },
            "dismissalTime": "2021-04-30T10:15:00.00Z"
        }]
    }
}

Example persistent visual alerts

The following table shows example persistent alerts that you might display to your guests.

Type of alert Primary text Secondary text

Activities

Exercise reminder

Time to take a walk.

Activities

Activity tonight at 7:00 PM

Come join us for activity.

Appointments

Your appointment reminder

Your appointment starts at 3:00 PM.

Services

Continental breakfast

Breakfast is served until 1:00 PM.

Maintenance

Your TV is fixed

Background images for proactive suggestions and visual alerts

For both proactive suggestions and visual alerts, you can provide a background image. Use the following guidelines for your images:

  • You can provide images in PNG or JPG format.
  • The image files can't exceed 400 KB in size.
  • Each template scales the image uniformly up or down to completely fill the screen ("best-fill"). This means that the image might get cut off if there is a mismatch between the aspect ratio of the image and the device screen. Therefore, consider the following recommendations:
    • Avoid using images with text that extends to the edges of the image, as this text might be truncated due to the scaling.
    • If possible, test your images on the same device types used in your units.
    • If separate units contain different devices, consider targeting the different units with separate cards or alerts so that you can optimize the images for the devices. This strategy works when all the devices in a given unit have the same aspect ratio.

Multimodal device FAQ

The following frequently asked questions (FAQ) answer common questions about customizing Alexa-enabled multimodal devices.

Q: What's the maximum number of cards that I can display?
You can send any number of proactive suggestions, but the maximum number of cards that Alexa can display is 20. Alexa displays the first 20 cards based on creation date, from the newest to the oldest.
Q: What percentage of time does Alexa show proactive suggestions?
Alexa displays cards at a 4:1 ratio of developer-submitted cards to Alexa-submitted cards.
Q: What's the size limit for background images?
The maximum image size is 400 KB in alerts. For more about images, refer back to Background images for proactive suggestions and visual alerts.
Q: What formats does Alexa support for background images?
Alexa supports images in JPG or PNG image format. For more about images, refer back to Background images for proactive suggestions and visual alerts.
Q: How do I specify images that aren't the same size or aspect ratio as the viewport of the device?
For an alert or proactive suggestion, the template scales the image uniformly up or down to completely fill the screen ("best-fill"). For more about images, refer back to Background images for proactive suggestions and visual alerts.
For an APL document you provide in a property skill response, you can specify how to scale images. The recommended templates for these responses each include a backgroundScale parameter you can set to determine scaling. For example, see Headline.
Q: How do visual alerts and proactive suggestions work with screen saving mode?
When a persistent visual alert is displayed, the device shouldn't go into screen saving mode. Proactive suggestions don't impact screen saving mode.
Q: How many suggestions can I add to a campaign?
You can add one suggestion per campaign. If you want Alexa to display more than one card, you create one campaign for each suggestion.
Q: What are the required properties for visual alerts and proactive suggestions?
The required properties depend on the template you use for the alert or suggestion. For example, the Text wrapping template requires the primaryText property. For details about proactive suggestion templates, see Campaign templates. For details about templates for alerts, see Persistent visual alert templates.
Q: Is there a maximum end date that I can specify in proactive suggestions?
No. You can specify any end date.
Q: How soon does the card display after the Proactive Suggestion REST API request?
Usually, Alexa displays the on-screen alert within two hours of receiving the request. If the guest power-cycles the device, the device flushes the current rotation and displays the latest suggestion.
Q: How soon does the alert display after the Notifications REST API request?
Usually, Alexa displays the on-screen alert within five minutes of receiving the request.

Was this page helpful?

Last updated: Mar 20, 2024