Archive

Since launch, the Alexa Skills Kit has offered you the ability to display text-based information through a Home Card in the Amazon Alexa companion app available for Fire OS, Android, iOS, and desktop web browsers. These cards are a useful way to provide users with additional information from your Alexa skill that is too verbose or too difficult to include in the voice user interface.

Now you can embed images inside of Home Cards to make your cards more engaging. You’ll add images in a new type of Home Card that we are calling Standard. You simply provide the URLs to your images in addition to the title and text you provide for Simple and LinkAccount home cards.

Creating a Standard Home Card

When you create a Home Card, you will provide textual information (in both PlainText and SSML) along with an image. Here is an example of a card that I have added to my own skill hosting in AWS Lambda using the well-known alexa-skills-kit-color-expert blueprint.

When my skill’s LaunchRequest returns it’s JSON response you can see both the SSML as well as a new image inside of the Alexa App, in this case running on my iPhone.

Creating a similar card in your own Alexa skill is a simple process and involves updating your existing Home Card JSON response and adding the proper permissions to your hosted image as follows:

Set the type to Standard.

Set the title and text properties to the text to display.

Note that this type of card uses a text property, not a content property like Simple.

Use either “\r\n” or “\n” within the text to insert line breaks.

You can use both PlainText and SSML

Include an image object with smallImageUrl and largeImageUrl properties.

Set smallImageUrl and largeImageUrl to the URLs of a small and large version of the image to display.

Here is what the updated Home Card JSON response looks like in my own skill:

Call the object’s setTitle() and setText() methods to set the title and content.

Create an Image object and assign the URLs with the object’s setSmallImageUrl() and setLargeImageUrl() methods.

Pass the Image object to the StandardCard object with the setImage() method.

Pass the StandardCard object to either SpeechletResponse.newTellResponse() or SpeechletResponse.newAskResponse() to get aSpeechletResponse that includes the card.

Creating Home Card Images

In the example above, I have provided two URLs: a smaller resolution image and a larger resolution image. The different sizes are used when displaying home cards on different sized screens. It is recommended you follow similar sizes for the best results:

Property

Description

Recommended Size (in pixels)

smallImageUrl

Displayed on smaller screens

720w x 480h

largeImageUrl

Displayed on larger screens

1200w x 800h

Please Note: Images must be in PNG or JPG format and cannot exceed 2MB. If you only provide one ImageURL, the Alexa app uses that image regardless of the screen size where it is displayed.

Setting the Home Card Image Permissions

The image files you provide must be hosted on an HTTPS endpoint that also meets the following requirements:

The endpoint must allow cross-origin resource sharing (CORS) for the images. This allows the Amazon Alexa app to download the image for processing and validation before displaying it in the Alexa app.

To enable CORS, the image server must set the Access-Control-Allow-Origin header in its responses. If you want to restrict the resources to just the Alexa app, allow just the origin http://ask-ifr-download.s3.amazonaws.com.

How you configure this depends on your image host. For example, if you host your images in an Amazon S3 bucket, you can configure the bucket with the following CORS configuration:

For my own skill, I chose to host using an S3 bucket and I set up a CORS configuration that included the Alexa app origin. To do the same for your own skills, simply navigate to the permissions section for your S3 bucket and click on Edit CORS Configuration.

This will bring up a new window where you can add an <AllowedOrigin> tag that ponts to the Alexa app origin.

After you have set up your CORS configuration in your S3 bucket do not forget to enable the correct permission for Everyone for your newly created images, similarly to how you would host an SSML audio mp3 file. Here is what my configuration looks like: