As you attract new customers to your skill, some may need help during different stages of the experience. Offering in-skill contextual help is a great way to guide your customers to help them get the most value from your skill. When integrating contextual help, you’ll want to ensure you’re adding value in a way that streamlines, not disrupts, the experience.

This post shares some examples of where contextual help can be most useful within an Alexa skill and best practices for implementing it.

Types of In-Skill Help Messages

There are two types of help messages in any Alexa skill. A master help message is a message the customer hears when they explicitly ask for help. These messages can make it easier for customers to discover skill commands and features. A contextual help message is an occasional help message that a custom skill should utter when it catches an error or detects that the customer is struggling with some commands or functions. These messages are especially helpful for skill functions with various options.

Best Practices for Writing Voice-First Help Messages

When writing your master help message, include the same details that are in the first-time welcome message, such as the most common functionality or popular intent. You can also give the customer examples of what to say in help messages. Additionally, consider sending a card to the customer’s Alexa app with those examples. You can tell the customer you’ve done so after providing some initial information with something like “I’ve sent a card to your Alexa app to tell you more.”

Skills that request linking to an account or manage device settings often benefit from a contextual help message to tell the customer how their settings or preferences might be used, such as a delivery address or a search filter. The contextual help message can be useful to tell the customer how they can change their settings or information.

You may also choose to write contextual help for search. If a customer receives no results in their search or receives more than two consecutive utterance errors, the skill can route them to a prompt that includes search tips, types of parameters they can ask for, and more.

Here’s an example:

Customer: “Alexa, ask PlayWithWords to continue my game.”

Alexa: “Welcome back to PlayWithWords. Resuming your game.”

Alexa: “Your last word is: H-P-T-N-A-E-E-L. What word am I thinking of?”

Customer: “Uh … help me.”

Alexa: Contextual help, “This animal never forgets.”

Alexa: Re-prompt, “What word am I thinking of?”

Customer: “Elephant!”

Alexa: “Great job. Your score is 8 out of 10. You can start a new game or hear about your all-time score. Which would you like?”

Customer: “Help.”

Alexa: Routes to master help message, “You’re playing PlayWithWords, the skill that builds your vocabulary with fun games like scrambling and hangman. Each day I’ll have a few new words for you to learn. I’ll keep track of your scores so you can see how you compare to your friends.”

Alexa: Re-prompt, “You can start a new game or hear about your all-time score. Which would you like?”

You can leverage the fallback intent to utter contextual help. You can also implement it whenever one of the intents catches an unexpected slot value, which indicates that this is an erroneous scenario.

Guide Customers on How to Use Their Smart Home Custom Skills

Custom skills that offer feature control (like a suite of smart home devices) may choose to provide contextual help for specific control types to let the customer know about those particular controls and their limitations. That might sound something like: “You can ask me to set the temperature in your oven. You can ask for a Fahrenheit or Celsius, and I’ll save your preference for the future. I can set the temperature between # and # Fahrenheit, or # and # Celsius.”

Here’s another example:

Customer: “Alexa, ask HomeBot to turn on the oven.”

Alexa: “Is that your upper or lower compartment?”

Customer: “The upper.”

Alexa: “Ok, what temperature would you like your upper compartment?”

Customer: “Extra hot.”

Alexa: “Hmm. I’m not sure about that. What temperature?”

Customer: “Make it hotter.”

Alexa: Routes to contextual help message about temperature, “You can ask for a temperature between 170 and 550 degrees Fahrenheit, or 65 and 280 degrees Celsius.”

Alexa: Routes back to original prompt, “What temperature would you like your upper compartment?”

Customer: “375 degrees.”

Alexa: “Ok. I am setting your upper compartment to 375 degrees Fahrenheit.”

Contextual help prompts should end with an invitation to the customer to try again in the form of a question, which will keep the conversation seamless and more natural. Retain a counter in the session variables to keep track on how many times the skill sends help messages. After two or three attempts to correct the customer, we recommend throwing in a home card and gracefully terminating the session by asking the customer to refer to the home card for more assistance.

Provide Troubleshooting and FAQs during Skill Enablement

Many customers would appreciate help and guidance when they are first getting started with your skill. If your skill requests account linking from the customer, make sure to follow account linking best practices. Additionally, present a button or link to a dedicated help page that addresses the most frequently asked questions and provide solutions for common issues. If your skill is a smart home skill, add a section to list the devices supported along with compatible models to enforce a device compatibility check for smart home skills.

For smart home skills, customize your account-linking page by designing a landing page with visual checkbox icons where each one represents a device/model supported like a wizard flow.

Once the customer selects at least one appliance, the enablement process can proceed with presenting your account linking authentication page.

Add a link for customers to visit if they can’t find their owned devices. This link should direct the customer to a help page or contact us form, which should be a direct channel for customers to ask for specific device support. Make sure you respond to these requests and inform customers whether their devices will be supported shortly, or that you don’t have plans for that.

Please note that when you implement help pages, the URL provided must either be owned by the skill developer (the developer name must be customer-facing in the skill's description in the Alexa Skills Store) or the name of the skill’s brand or owner company.

Build Helpful Voice Experiences

As skills combine various functions and offer multiple benefits, it can be a drawback when the skill doesn’t accurately guide customers through the experience with sufficient help. By creating richer help that’s contextualized throughout the voice interaction, you’re able to create positive and engaging experiences for customers.

More Resources

For more information about adding contextual help throughout your skill, check out the following resources:

• Alexa Voice Design Guide: How Alexa Responds
• Use the New Fallback Intent to Respond Gracefully to Unexpected Customer Requests
• 10 Tips for Successfully Adding Account Linking to Your Alexa Skill
• Beyond the Basics: Best Practices for Adding Account Linking to Your Alexa Skills
• Alexa Skills Kit (ASK)
• Alexa Developer Forums

Make Money by Creating Engaging Skills Customers Love

When you create delightful skills with compelling content, customers win. You can make money through Alexa skills using in-skill purchasing or Amazon Pay for Alexa Skills. You can also make money for eligible skills that drive some of the highest customer engagement with Alexa Developer Rewards. Learn more about how you can make money with Alexa skills, and download our guide to learn which product best meets your needs.