The Alexa Skills Kit provides the ability to display visual information, both text and images, via skill cards. These cards are a useful way to provide your users with additional information from your Alexa skill that may be too verbose or too difficult to include in the voice user interface. Skill cards can be displayed in many form factors across different types of devices. This includes the Alexa app via iOS and Android devices, the Alexa app via a web browser, on Fire Tablet, and on the big screen while interacting with skills on Fire TV.
There are currently three types of skill cards you can create: Standard, Simple and LinkAccount.
When you create a skill card, you will provide textual information (in both plain text and SSML) along with an optional image. Here is an example of a Standard 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 its 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.
You can see I have provided the following information in the card:
Creating a similar card in your own Alexa skill is a simple process and involves updating your existing skill card JSON response and adding the proper permissions to your hosted image. For more information on the building a JSON skill card response check out this post.
1. You may have noticed something in the skill card above however, that doesn’t look quite right. While having SSML tags is important to enabling a more human like conversation with Alexa it will appear as a bunch of gibberish to your users. By default, SSML is not stripped out of the skill card display which is why you are seeing both the <speak> and <break> tags rendered. This is a common skill card error we have seen during Alexa skill certification and one that can easily be fixed using a regex expression or string replace.
2. You can also use either “\r\n” or “\n” within the text of the card to insert line breaks. Use line breaks to help format individual lines of addresses, product details or information. However, we don’t recommend adding double line breaks when separating parts of a street address to make this content more easily legible.
3. Keep your text responses short, informative and clear: Structure text for cards in brief, informative sentences or lines of text. Avoid unstructured product details.
4. Also, don’t rely on large blocks of text but instead keep details to a minimum so your users can evaluate the card at a quick glance.
5. Since URLs in cards are not clickable links, don’t just include URLs on cards to direct users to other sites. Instead, provide instructions to direct the user vocally. For example, have Alexa say, “Go to the Settings section of (the website name).”
You should write the text on your cards like you would in a document. Use sentence case for body text and title case for headlines. Also, don’t forget to do a grammar check! Unlike your Alexa response, the text here is not going to be read aloud by Alexa; it is going to be displayed exactly as you type it.
Skill card images are displayed in two different sizes: a smaller resolution image and a larger resolution image. The different sizes are used when displaying skill 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 Image URL, the Alexa app uses that image regardless of the screen size where it is displayed.
Here are some tips for generating an image that will provide the best experience to your user:
Fire TV also introduces variability in the card experience due to the size of the viewing screen and its inherent design elements. Here are some things to keep in mind when designing your cards:
Think about how often you are using a skill card. Is it in every single response you send to Alexa? That might be ok while you are debugging your skill, but it may overload your user with too much information.
Don’t make viewing cards a necessary step. You should strive to include all important information in your voice experience while the visual card provides additional, optional information.
Skill cards make perfect sense when they provide additional information about a specific piece of content. For example, providing an image of an owl in an animal trivia skill or perhaps an album cover in a music streaming skill.
The Alexa mobile app has a scrollable history, but the Fire TV does not support a history of skill cards. Therefore, it is important to use cards as one-off individual experiences
Use cards as individual experiences: Don’t depend on the card before or after using the skill since the user might not be able to access it.
Don’t expect users to save information on the cards as they can’t be saved. For instance, while details about a transaction are useful as a card, the card can’t serve as a transaction receipt since the user can’t save it. In addition, users can’t search for old cards.
Cards can be a great way to get a lost user back on track, or enable self-service to show users what they can do.
Provide guidance: Give enough detail for the user to move forward when lost – without going overboard. Suggest sample utterances when they need help.
Also, keep the timing and context in mind. Don’t offer utterances on a card that can’t be used in the context of the current situation. For example, don’t suggest a checkout utterance on a card when there aren’t any items in the user’s cart yet.
Think of skill cards as a way to build on the overall conversation, not simply a log of information to spew out while your user is interacting with Alexa. Keep it interesting: don’t re-use the same content over and over again or your users may begin to ignore the cards all together. Instead, delight the user with moments of surprise and visually interesting images based on the relevant content they’ve asked for.
For more information about Alexa skill cards, check out the following:
Best Practices for Skill Card Design
Including a Card in Your Skill's Response
Voice Design Best Practices Video
Alexa Developer Forums
Alexa Dev Chat Podcast
-Dave (@TheDaveDev)