Your Alexa Dashboards

Your Alexa Dashboards Support

Include a Card in Your Skill's Response

Interactions between a user and an Alexa device can include home cards displayed in the Amazon Alexa App, the companion app available for Fire OS, Android, iOS, and desktop web browsers. These are graphical cards that describe or enhance the voice interaction. A custom skill can include these cards in its responses.

A skill developed for Echo Show can also support display templates, which are similar to cards and are viewed directly on the Echo Show device. See Display Interface Reference. Echo Show also displays cards that have been designed for display in the Alexa app, so skills that include cards designed for display in the Alexa app will also display those cards on Echo Show, if that is the device that the customer uses.

Overview of Cards
Creating a Basic Home Card to Display Text
Creating a Home Card to Display Text and an Image
Defining a Card for Use with Account Linking
Related Topics

Overview of Cards

For example, a skill for looking up tide information could include a home card containing the tide information the user asked for. The user can use this to get back to the information from the skill without making another voice request.

Example of a home card for Tide Pooler — Example of a Home Card for Tide Pooler

Home cards can be very useful for enhancing interactions. For instance, voice responses need to be concise and “written for the ear”. A home card can provide additional, useful details that would make the voice response too verbose or too difficult to understand as speech.

The Alexa Skills Kit provides different types of home cards:

A Simple card displays plain text. You provide text for the card title and content.
A Standard card also displays plain text, but can include an image. You provide the text for the title and content, and the URL for the image to display.
A LinkAccount card is a special card type only used with account linking. This card lets users start the account linking process.

To send a card to the Alexa app, you include the home card in the response your service sends back to Alexa. You typically only return home cards when responding with the information the user requested. Other responses, such as questions to ask the user for more information do not normally include home cards.

To view the home cards, open the Alexa app and click Home.

For recommendations to design effective cards, see Best Practices for Skill Card Design.

Creating a Basic Home Card to Display Text

The simplest home cards consist of plain text. You provide the title and content and the Alexa app displays the card:

Note that the total number of characters (both title and content combined) for the card cannot exceed 8000.

To create a simple card, include the card property in your JSON response:

Set the type to Simple.
Set the title and content properties to the text to display. Use either “\r\n” or “\n” within the content to insert line breaks.

{
  "version": "1.0",
  "response": {
    "outputSpeech": {"type":"PlainText","text":"Text to speak back to the user."},
    "card": {
      "type": "Simple",
      "title": "Example of the Card Title",
      "content": "Example of card content. This card has just plain text content.\nThe content is formatted with line breaks to improve readability."
    }
  }
}

When using the Java library:

Create a SimpleCard object.
Call the object’s setTitle() and setContent() methods to set the title and content.
Pass the card object to either SpeechletResponse.newTellResponse() or SpeechletResponse.newAskResponse() to get a SpeechletResponse that includes the card.

Creating a Home Card to Display Text and an Image

A home card can include a single image. In this case, you provide the title, text, and two URLs (a small version and large version) for the image to display.

Example of a Standard Card with an Image

Note that the total number of characters (title, content, and both URLs combined) for the card cannot exceed 8000. Each URL cannot exceed 2000 characters.

To create a card with an image, include the card property in your JSON response:

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.
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. See below for details about the image format, size, and hosting requirements.

{
  "version": "1.0",
  "response": {
    "outputSpeech": {"type":"PlainText","text":"Your Car-Fu car is on the way!"},
    "card": {
      "type": "Standard",
      "title": "Ordering a Car",
      "text": "Your ride is on the way to 123 Main Street!\nEstimated cost for this ride: $25",
      "image": {
        "smallImageUrl": "https://carfu.com/resources/card-images/race-car-small.png",
        "largeImageUrl": "https://carfu.com/resources/card-images/race-car-large.png"
      }
    }
  }
}

When using the Java library:

Create a StandardCard object.
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 a SpeechletResponse that includes the card.

Image Format and Size

You can provide images in the following formats:

JPEG
PNG

An image cannot be larger than 2 MB.

When including an image, you provide two URLs: a smaller resolution image and a larger resolution image. The different sizes are used when displaying home cards on different sized screens:

Property	Description	Recommended Size (in pixels)
`smallImageUrl`	Displayed on smaller screens	720w x 480h
`largeImageUrl`	Displayed on larger screens	1200w x 800h

For best results on different screens that can display home cards, provide both smallImageUrl and largeImageUrl. If you only provide one URL, the Alexa app uses that image regardless of the screen size where it is displayed. This may cause your home cards to display poorly. For example, if you only provide smallImageUrl, the Alexa app must scale up that image when displaying on larger screens, which could degrade the quality of the image.

Using images close to the recommended sizes ensures the quality of the image in the app. Smaller images may be scaled up to display in the app, which can degrade image quality. Large images take longer to load, so using images that are larger than necessary can slow the performance of rendering the cards in the app.

For instance, in this example, the Alexa app has scaled up a very small image:

Example of a Standard card with a very small image that must be scaled up

Be sure to test your home cards in the Alexa app (ideally on different devices with a variety of screen sizes) to ensure that the cards display well.

Hosting the Images

The Alexa app loads the images from the provided URL at runtime. The image files you provide must be hosted on an HTTPS endpoint that meets the following requirements:

Endpoint provides an SSL certificate signed by an Amazon-approved certificate authority. Many content hosting services provide this. For example, you could host your files at a service such as Amazon Simple Storage Service (Amazon S3) (an Amazon Web Services offering).
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 origins http://ask-ifr-download.s3.amazonaws.com and https://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:

<?xml version="1.0" encoding="UTF-8"?>
<CORSConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
    <CORSRule>
        <AllowedOrigin>http://ask-ifr-download.s3.amazonaws.com</AllowedOrigin>
        <AllowedMethod>GET</AllowedMethod>
    </CORSRule>
    <CORSRule>
        <AllowedOrigin>https://ask-ifr-download.s3.amazonaws.com</AllowedOrigin>
        <AllowedMethod>GET</AllowedMethod>
    </CORSRule>
</CORSConfiguration>

For more about S3 and CORS, see Enabling Cross-Origin Resource Sharing.

Note: The images must also be publicly available and the URL for the image must not be set to expire. If you use Amazon S3, be sure to make the images public and do not configure an expiration time.

Common Issues when Including Images in Standard Cards

This section describes some common issues that may occur when you include an image in a Standard card.

Image displayed as a gray box: This can occur for several different reasons:

Missing images: The image URLs you provide don’t point to actual images, reference images that are not publicly available, or are URLs that have expired.

Note: If you use Amazon S3 to host your images, be sure to make them public and non-expiring. Some hosting solutions (including Amazon S3) allow you to set an expiration time on an image URL. In this case, the URL becomes invalid once that time passes. Since the Alexa app loads the image from the provided URL at runtime, the URL must always point to a valid image. Do not set an expiration time on the URLs you use for your images.
Image host not CORS-enabled: The server hosting your images is not CORS-enabled.
Incorrect image format: The image URLs reference images that are not in one of the supported formats (PNG or JPEG).
Image is too large: the file size for the image you provided is greater than 2 MB.

Example of a Standard card with missing images

Card displayed with no image and no placeholder: This can occur if your response doesn’t include an actual image object. The card is still displayed, but with no image.

For example, note the following JSON. This is specified as an Standard card, but with no image:

{
  "version": "1.0",
  "response": {
    "outputSpeech": {"type":"PlainText","text":"Your Car-Fu car is on the way!"},
    "card": {
      "type": "Standard",
      "title": "Ordering a Car",
      "text": "Your ride is on the way to 123 Main Street!\nEstimated cost for this ride: $25"
    }
  }
}

This creates a card that looks like this:

Example of a Standard Card with no image object specified

Defining a Card for Use with Account Linking

Some Alexa skills require the ability to connect the identity of the end user with a user in another system. This is referred to as account linking, since the goal is to create a link between the Alexa user and the user account in your system.

If the user invokes an intent that requires this link and the link has not yet been established, the skill normally sends back a response directing the user to use the Alexa app to link their account. The card displayed in the app is a special card type that lets the user connect their account:

Most of the content is generated automatically from your skill’s configuration:

The card title is set automatically from the name of your skill (“Car-Fu” in the above example).
The text (“To get the most…”) is standard for all skills that use account linking.
The link (“Link Account”) goes to the Authorization URL you configure in the developer portal when setting up account linking for your skill.

To create an account linking card, include the card property in your JSON response. Set the type to LinkAccount and pass no other properties.

{
  "version": "1.0",
  "response": {
    "outputSpeech": {"type":"PlainText","text":"Please go to your Alexa app and link your account."},
    "card": {
      "type": "LinkAccount"
    }
  }
}

When using the Java library:

Create a LinkAccountCard object.
Pass the card object to SpeechletResponse.newTellResponse to get a SpeechletResponse that includes the card. Note that you should not use SpeechletResponse.newAskResponse in this case since it does not make sense to leave the session open after telling the user that they must link their account before they can use the skill.

See Linking an Alexa User with a User in Your System for details about implementing account linking.

Include a Card in Your Skill's Response

Overview of Cards

Creating a Basic Home Card to Display Text

Creating a Home Card to Display Text and an Image

Image Format and Size

Hosting the Images

Common Issues when Including Images in Standard Cards

Defining a Card for Use with Account Linking

Related Topics