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 (1^st, 2^nd, 3^rd Generation)
• Amazon Echo Show 8 (1^st, 2^nd, 3^rd 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 until the user dismisses the alert. To send visual alerts, you can use the Notifications API or the Alexa Smart Properties Console.

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.

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 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.

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.

Send persistent visual alerts

A persistent visual alert is a notification that displays a visual alert on a device with a screen. The alert remains visible on the device until the guest or resident dismisses the alert or the alert expires. Persistent visual alerts are sometimes called "pinned cards," because they remain "pinned" on the device until the user dismisses them. Use persistent visual alerts for upcoming events, appointments, and other information you want your guests or residents to see.

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 about the templates, see Persistent visual alert templates.

Alternatively, you can use the Alexa Smart Properties Console to send a persistent visual alert using a default template. 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 the API request to create a visual alert that uses the Text wrapping template to remind the guest to take a walk.

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.

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.

Related topics

• Visual Design: Alexa Presentation Language
• Tutorial: Add Your First Visual Response to a Custom Skill
• About Alexa Smart Properties

Last updated: Aug 07, 2024