Build an Alexa Sounds Skill and Monetize your WordPress Website

Alexa-enabled devices account for about 70% of all smart speaker sales in the US, and Amazon reports that there are 100 million of them currently in use. With that thriving market in mind, Amazon has been gradually introducing ways for developers to make money off of the skills they build.

One of those ways is In-Skill Purchasing (ISP), introduced in May 2018. It allows skill creators to sell items either through one-time purchases or subscriptions.

In this post, you’ll learn about In-Skill Purchasing, how to use it with Convoworks, and get one ambient sounds skill to experiment with.

Let’s get started!

What is in-skill purchasing (ISP)?

The in-skill purchasing feature lets skill creators sell premium digital content in their skill. However, the ISP content shouldn’t overshadow the skill’s free content, it should enhance it. In other words, it should add high-quality content to an already engaging experience. With these guidelines in mind, we created our own skill you’ll get to know in the later sections.

But first, let’s talk about some In-Skill Purchasing basics.

In-Skill Purchasing allows skill creators to offer and sell digital content. A skill can promote (upsell) a specific premium content, or the user can outright ask to buy the content by saying something like, “I want to buy <product name>“. Furthermore,  the user should be able to request and get in-skill information about already purchased and available products. And last but not least,  the skill must support purchase cancellation or refund requests.

As for the types of digital products we can sell, there are three in total:

• Consumable: Provides access to premium content that is depleted upon usage and can be purchased again —for example, paid hints for a trivia game.
• Subscription (recurring purchase): Users get charged on a recurring basis, either monthly or yearly until they decide to cancel their subscription—for example, a podcast skill with regularly updated episodes.
• One-time purchase: Provides access to premium content that never expires—for example, additional themed packs in a trivia game.

That’s it for the ISP basics. For more information, you can continue your research here. Now, let’s take a look at the ISP implementation in Convoworks.

ISP in Convoworks

Convoworks developed three specialized components to handle the in-skill purchases for you. They are a part of the convo-alexa package and handle different in-skill purchasing technical requirements.

Elements

We have two ISP elements that you can use in your Convoworks service: The Get In-Skill Products Element and the Sales Directive Element.

Simply put, the Get In-Skill Products Element lets you access the purchased or available products by product type.

As for the Sales Directive Element, it sends a Connections.SendRequest directive for a buy, upsell or cancel request. For example, we can use the buy intent triggered by the user in conjunction with the Sales Directive Element to trigger the purchase flow.

Once we send out any of these directives, the current skill session ends. Alexa takes over the transaction and uses predefined values from products that we defined in the Alexa Developer Console. We will touch on how to define those values in the Configuring our In-Skill Product section.

After the transaction is over, Alexa relaunches the skill. This is where our Sales Block plays a part.

Blocks

After Alexa relaunches the skill, we receive the transaction result as a Connections.Response request. This request helps us resume the skill session where the user left off. The session resumes in the Sales Block, which processes the aforementioned Connections.Response request. In this block, we can check if the purchase transaction went well by accessing the purchaseResult variable.

The variable can have one of the following values:

• ACCEPTED
• DECLINED
• ALREADY_PURCHASED
• ERROR

Now that we’ve laid down the groundwork, it’s time to import the example service into Convoworks.

Importing the sounds skill into Convoworks

Ambient sounds are wildly popular on Alexa. In fact, they dominate the Top Alexa Skills category, with four top skills at the time of writing this post being ambient sounds. Also, all of them offer additional content through In-Skill Purchases.

This led us to create our own sounds skill – Forest Sounds. The Forest Sounds skill plays one free forest sound in a loop and offers one additional, premium sound for sale.

In this section, we’ll share it with you. You can follow the steps below to download and import Forest Sounds into your Convoworks service.

First,  download the Forest Sounds service definition below.

Service definition

Now, navigate to Add new service view in Convoworks WP and select the Import from file option. Upload the service definition you downloaded from the link above.

If this is your first time using Convoworks, you might want to check out our “Connect to Amazon and create your first Alexa skill tutorial” from the Convoworks Basics video series. Otherwise, navigate to the Configuration view and publish the service to Amazon.

Before we can test our new service, we have to configure ISP in the Developer Console and finally add the forest sounds in question.

Configuring our In-Skill Product

While we are done setting up our service, the product we will sell still needs to be created in the Amazon Developer Console. Amazon has built a monetization tool in the Developer Console which lets users add in-skill products in just a few steps.

Creating the product

First, open the skill you’ve just deployed in the Developer Console.

Next,  on the Build tab of your skill’s developer page, select the MONETIZE YOUR SKILL item from the left-hand menu. Select the Add In-Skill-Products model. If you cannot see the MONETIZE YOUR SKILL section, click on TOOLS first, which will open another dropdown menu. From there you should see MONETIZE YOUR SKILL.

After that, click the Create in-skill-product button. You’ll be redirected to a form that defines the product’s reference name and type.

Give the product the following (reference) name: ForestNightSounds. This name is used in Convoworks to get the in-skill product information, so the names must match exactly. As for the product type,  choose a One-time purchase.

A new screen should appear next. This is where we configure our product. It entails adding details like supported languages, price, icon, etc.

Configuration for the locale

Let’s start by adding supported languages. Click on the Add new language link and add only the English (US) option.

You will be redirected to a page where you can start filling in the following product details:

• Display name: The name of the product for this locale. This name is included in purchase confirmation prompts, Alexa app purchasing cards, and email receipts.
• One sentence description: A quick at-a-glance sentence that describes the product or what customers can do with it.
• Detailed description: A full description explaining the product’s functionality and any prerequisites to using it. This description is used in offer and purchase cards on screen devices.
• Example phrases: List of example phrases that illustrate how users can ask for your in-skill product. These phrases must be supported in your voice model.
• Purchase prompt description: The description of the product a customer hears when making a purchase.
• Purchase confirmation description: A description of the product that displays on the post-purchase confirmation card in the Alexa app.

For now, feel free to use placeholder text, but remember to replace it if you plan on publishing the skill.

In addition to filling in the text fields, you will need to create and add product icons. You can use the Alexa Skill Icon Builder to create a set of icons in the right sizes quickly.

Once you are finished, click the Save button at the top of the page. You will be redirected back to the main product page.

Main product page configuration

On the main product page, we still need to define the Pricing & Availability and Tax Category. Let’s start with Pricing & Availability. Click on the checkbox next to Amazon.com to enable the option. Leave the default price. Next, scroll down to view Tax Category. You can read up on tax requirements for skills that generate revenue here. For now, just select Streaming audio to complete this step.

Lastly, there are the Testing Instructions at the bottom of the page. Feel free to use placeholder text there as well.

And that’s it! You can now click the Save button at the top of the page. After that, you will be prompted to link the product to your skill. Confirm the linking with Link to skill.

Now that we have set up our in-skill product, we can move on to importing the forest sounds we’ll use for this skill.

Importing the sounds into WP Media Library

Convoworks has a specific component developed for playing audio files called Audio Player. However, for the Audio Player to play the files, we must define where the system can find them. Without getting into technical details, we defined the sound source in our Forest Sounds skill as WP Media Library. We’ll search the sounds by their names Standard Forest Sounds and Forest Night Sounds. The first is a free version, and the second is a premium one which we’ll suggest to the user at an appropriate time.

The first step is finding the right sounds. We got ours from freesound.org: Standard Forest Sounds, Forest Night Sounds. However, if you plan on publishing the skill, it might be best you purchase yours to avoid any attribution requirements.

Second, rename the sounds and upload them to the WP Media Library.

And lastly, edit the sounds titles to match their in-skill display names Standard Forest Sounds and Forest Night Sounds. Otherwise, the search system won’t find them.

One thing to note — the file you downloaded might not have File type set to audio/mpeg. Instead, it might be something like audio/wav. If that is the case, copy the file type, go to your Convoworks skill and click on the Contexts tab on the right-hand side. Click on the WP_Query mp3 source context, and edit the post_mime_type value to reflect your file type.

That’s it! We should now have a fully functional skill we can test.

Testing the skill

Our avenues for testing are limited. We cannot test the in-skill purchasing and audio player with the Convoworks chat interface. On top of that, the Alexa simulator on the Test page of the Developer Console also can’t render the audio playback.

This leaves us with two options: we can test the skill with the Alexa app or one of the Alexa-supported devices.

To start testing, simply invoke the skill with “open <skill name>“. For now, just make sure the skill is streaming the audio correctly.

In the next section, we’ll take a closer look at the skill’s workflow and design.

Skill overview

So far, we haven’t discussed the skill’s workflow, nor how we designed the ISP voice experience. This section is going to address that. We’ll start with the sample dialogues and the why of certain design decisions. Next, we’ll look at the skill’s workflow and components in Convoworks.

Example dialogues

Beyond the ISP flows, the skill doesn’t feature much dialogue. In most cases, we don’t want to disturb our users with needless dialogue. So, when the user opens the skill, they are greeted with our forest sounds. The longer interactions are mostly user-initiated ISP transactions.

Upsell flow

One of the exceptions is the skill initiated upsell flow at the beginning of the third skill session.

Let’s analyze it now:

User: Alexa, open Forest Sounds

The skill checks if this is the user’s third visit and the product is available for purchase. The skill then sends a directive that indicates an upsell request. This ends the current skill session.

Alexa (upsell message): Glad to have you back! If you’d like to experience the peaceful night sounds of the Sian Ka’an Biosphere Reserve, you can now get the Forest Night Sounds. Want to hear more?

User: Yes.

Alexa (purchase prompt description + price + prompt): Purchasing the Forest Night Sounds pack will give you one extra sound you can play anytime. Prime members save 19 cents. Without Prime your price is 99 cents plus tax. Would you like to buy it?

User: Yes.

Alexa: Great. Your order is complete and I’ve sent you the receipt.

Alexa relaunches the skill session in the Sales block

Alexa: You can now say things like ‘Tell Forest Sounds to play night sounds’. Would you like to play them now?

That’s what our upselling experience looks (sounds) like. If the user decides not to buy the product, we will suggest it again at the beginning of the tenth skill session. In case the user declines again, we will stop suggesting that product.

Let’s move on to the purchase flow.

Buy flow

User: Alexa, tell Forest Sounds I want to buy night sounds

The user triggered the BuyIntent. The skill sends a directive that indicates a buy request. This ends the skill session.

Alexa (purchase prompt description + price + prompt): Purchasing the Forest Night Sounds pack will give you one extra sound you can play anytime. Prime members save 19 cents. Without Prime your price is 99 cents plus tax. Would you like to buy it?

User: Yes.

Alexa: Great. Your order is complete and I’ve sent you the receipt.

Alexa relaunches the skill session in the Sales block

Alexa: You can now say things like ‘Tell Forest Sounds to play night sounds’. Would you like to play them now?

As you can see, except for the omitted upsell message, there is not much difference between the buy and upsell flows. But what happens if the user doesn’t know what products are available for purchase?

What can I buy flow

The user triggers the what can I buy flow when they ask for the available in-skill products. In other words, they don’t specify the product they want to buy, and instead, say something like, ‘What can I buy?’.

For example:

User: Alexa, ask Forest Sounds what can I buy

The user triggered the WhatCanIBuyIntent. The skill checks the number of available products. If that number is 1, it directs the user to the upsell flow. This ends the current skill session.

Alexa (upsell message):  If experiencing the peaceful night sounds of the Sian Ka’an Biosphere Reserve sounds interesting, you can get the Forest Night Sounds. Would you like to hear how to get them?

User: Yes.

Alexa (purchase prompt description + price + prompt): Purchasing the Forest Night Sounds pack will give you one extra sound you can play anytime. Prime members save 19 cents. Without Prime your price is 99 cents plus tax. Would you like to buy it?

User: Yes.

Alexa: Great. Your order is complete and I’ve sent you the receipt.

Alexa relaunches the skill session in the Sales block

Alexa: You can now say things like ‘Tell Forest Sounds to play night sounds’. Would you like to play them now?

Again, almost identical to the previous upsell flow. The dialogues would only diverge if we added more than one available product. But since we are keeping it simple in this post, with only one additional product, we will leave adding more products up to you.

Now, we still have two more flows to go over.

What did I buy flow

Since we already have a what can I buy flow, it is not unreasonable to expect the user to ask about the products they bought as well. This flow should serve you well especially if you plan on adding more products. With multiple purchases, the user might forget which sounds they have at their disposal.

You can see below how the skill responds when the user who previously purchased one pack asks, “What did I buy?”

User: Alexa, ask Forest Sounds what did I buy

The user triggered the WhatDidIBuyIntent. The skill checks the number of purchased products. 

Alexa: Let’s see. Besides the free, standard forest sounds, you have the Forest Night Sounds. Would you like to listen to any of them now?

This flow would pivot into the what can I buy flow, if the skill determines the user does not own any products. Speaking of which, if we allow purchases, we also have to support refund requests.

This leads us to our last example.

Refund flow

User: Alexa, tell Forest Sounds I want a refund for night sounds.

The user triggered the RefundSkillItemIntent. The skill sends a directive that indicates a cancel request. This ends the current skill session.

Alexa:  For a refund, check out the link I sent to your Alexa app.

And that’s it. We have covered most of our happy flow dialogues. Before you can start testing the flows to make sure the skill is working as expected. there’s one in-service modification you will have to make. First, navigate to the service page in Convoworks GUI. Next, select the Variables view. You will have to paste your own product id into the PREMIUM_SOUNDS_ID["ForestNightSounds"] value field.

To do that, first, delete the old id value. Second, head over to the Developer Console. You can find the product id at the top of the main ForestNightSounds page in your skill’s Developer Console. Simply copy and paste that value to the now empty PREMIUM_SOUNDS_ID["ForestNightSounds"] field. Lastly, save the changes.

You can now test out the skill. Since this is going to involve a lot of purchases and we only have one product for sale, you are going to have be resetting test purchases a lot.

To reset a test purchase, navigate back to your skill in the Developer Console. Click the In-Skill Products menu item in the Build tab. Under the ForestNightSounds product, there is a link to reset test purchases. Click the link and confirm the reset.

Congratulations on getting this far! You now have a fully functional skill with a product for sale.

Continue reading if you want to learn how to add more products.

Adding more premium sounds

In addition to Forest Night Sounds, the skill’s workflow in its current state supports adding two more premium sounds. This is because vocally presenting long lists causes cognitive overload. To put it simply, there’s only so much information we, humans can hold in our auditory memory.

If you had a larger number in mind you will have to make some adjustments to the skill. Specifically, you could send a card to their Alexa app with the list of all the purchased/available products.

Now, let’s go through the process of adding one more sound. Go ahead and repeat all the steps from the Configuring our In-Skill Product section. Of course, you will need to choose a different reference name and name.

When that part is done, open the service in the Convoworks GUI.

Intents view

First and foremost, our intents must be able to recognize the new product. Navigate to the Intents view. You will have to add the new product’s reference name to the ProductName entity. Add the reference name along with as much of relevant synonyms as you can think of. See the entity above for reference.

Variables view

Next, navigate to the Variables view. You will have to add a new PREMIUM_SOUNDS_ID variable that will store your product’s id. The PREMIUM_SOUNDS_ID variable is an associative array, and the new key should be your new product’s reference name, just like in the case of the PREMIUM_SOUNDS_ID["ForestNightSounds"] variable above.

You can find the product id at the top of the main product page in the Developer Console. Simply copy and paste that value.

The next modifications are in the service Editor view.

Upsell messages

In addition to making some modifications in Editor, you will have to come up with upsell messages for your new product.

First, select the Fragments tab on the Editor view. Next, open the Offer an upsell fragment. For every occurrence of an If Element evaluating if the name of the upselled product is “Forest Night Sounds”, you are going to have to add an Else If Element evaluating your new product’s name. Also,  in the Then flow of the element, you’re going to have to place a Sales Directive Element containing your upsell message. See the If flow above for reference.

Lastly, head back to the Steps tab and click the Home block. At the top of the Read Phase of the Home block, you can see an If Element evaluating whether an upsell flow should trigger. As we discussed before, the skill will trigger the upsell flow, that is offer a product if it’s the user’s third skill session. And of course, if there are any available products to offer. This flow has been designed with only one available product in mind, and definitely make some modifications here. Namely, which product gets offered when if there is more than one product available.

Given how the service is set up currently, the products will be upselled at the beginning of the third and the seventh sessions only. And if there is more than one product, the product will be picked at random.

As with the upsell messages you are going to have to make similar modifications to the buy and upsell request flows.

Let’s start with the upsell request flow.

Upsell request

Again, head back to the Fragments tab. This time, open the ProcessUpsellRequest fragment. For every occurrence of an If Element evaluating if the name of the upselled product is “Forest Night Sounds”, you are going to have to add an Else If Element evaluating your new product’s name. And then, add the appropriate Text Response Element message to the Then flow. Again, check the If flow above for reference.

If you don’t want to encourage variety in the way users invoke your product, you can skip adding the Else If Element. Instead, simply add the Text Response Element in the Then container of the Else flow.

Buy request

The process is pretty much the same for the buy request flow. First, open the ProcessBuyRequest fragment. Then, for every occurrence of an If Element evaluating if the name of the upselled product is “Forest Night Sounds”, you’ll have to add the appropriate Text Response Element message in either the Else If or Else flows.

The last step is going through the testing process again to make sure the skill is in working order.

That’s it. Congratulations on making it to the end!

Additional Resources

Even though you now have a fully functional skill with ISP you can publish, that does not mean it will pass Amazon’s certification process.

If you are interested in getting your skill certified, we recommend you review this additional documentation:

• Design a Good Customer Experience for ISP
• In-Skill Purchasing Overview
• Create and Manage In-Skill Products
• ISP Testing Guide
• ISP Certification Guide
• Set Up Tax Forms for Your Account
• Understand and Set Up Payments