1. Home
  2. Docs
  3. Publishers
  4. Platforms configuration
  5. Amazon Alexa

Amazon Alexa

We have two types of platform configurations for Amazon in the Convoworks GUI, the User Level, and the Service Level Configuration. The User Level Platform Configuration enables Convoworks to use Alexa SMAPI for creating and updating your skills remotely.

The Service Level Platform Configuration manages the service specific settings.

User Level Platform configuration – Admin Account Linking

You can view the User Level Amazon Platform Configuration form by clicking on the Configuration menu item in the Convoworks GUI and choosing Amazon Configuration from the dropdown (Settings sub-view for the WordPress version).

As you can see, you need the Client ID, Client Secret, and Vendor ID data. You can get that data from a Login With Amazon Security Profile. You’ll also need to add your return URL to the list of Allowed Return URLs on your app’s Security Profile before you can finally link your Amazon account.

Don’t worry, we’ll walk you through all the steps.

1. Create an Amazon Developer account

If you don’t have an Amazon Developer account already you can create one here:http://developer.amazon.com. Click the Sign In menu item and then Create your Amazon Developer account

2. Get Client ID and Client Secret

Log into your account then visit https://developer.amazon.com/dashboard and click on the Login with Amazon menu item. You can get the Client ID and Client Secret credentials by clicking on the Show Client ID and Client Secret if you have an existing Security Profile. If you don’t have a Security Profile, refer to the next section.

Create a New Security Profile

To register a new Security Profile click on the Create a New Security Profile. You have to supply your own Privacy Notice URL. The Privacy Notice URL is the location of your company or application’s privacy policy. You can read more about the Security Profiles here: Security Profile

3. Add a return URL

The next step is to add your return URL to the list of Allowed Return URLs on your app’s Security Profile. Allowed Return URL is the endpoint of your web app which provides the Login With Amazon Authorization Grant Code URL. More information about the Login With Amazon Authorization Grant Code URL can be found here: Authorization Code Grant.

If you are using Convoworks WordPress plugin, return URL is https://myinstallation.com/convo-process-oauth-callback and if you are using Convoworks Prototype the URL is https://mydomain.com/rest_public/convo/v1/admin-auth/amazon

Open the Login with Amazon Console and locate your Security Profile in the Login with Amazon Configurations table. Hover over the button and select the Web Settings menu item.  Once you’ve landed on the page, click the Edit button. Add your Allowed Return URLs and click Save.

5. Get Vendor ID

Finally, To get your Vendor ID just visit: https://developer.amazon.com/settings/console/mycid

5. Configure User Level Platform Configuration

Now, switch back to the Convoworks GUI and fill out the Amazon Platform Configuration. Click on the Save Configurations button once you’re done.

6. Link to Amazon Account

As the last step, click on the Configuration menu item and choose Link Amazon Account from the dropdown. Sign in to your account.

And that’s it for the User Level Configuration.

Service Level Platform Configuration for service propagation

Propagation allows Convoworks to deploy your app for you to a platform of your choosing, in this case, Amazon, and the Service Level Platform Configuration grants you access to service propagation.

Please note that the following properties of the Service Meta affect the configuration and the propagation result:

  • Service Name – service name translates to the Alexa Skill invocation name and will be propagated to the skill invocation part
  • Default Locale for Publishing Preview – this is used when getting existing publishing information of an existing Alexa Skill
  • Supported Locales for Publishing Preview – this is used for interaction model builds as well for sharing publishing information across different Amazon Supported locales after the propagation was completed

To access service configuration first select the service you want to configure from the Services view of the Convoworks Editor.

Then open the Configurations menu item, scroll down and click the Configure button on an Amazon Alexa card.

This will take you to the Amazon Alexa service configuration form.

We offer two modes of configuring the service for Amazon Alexa in Convoworks. The first one is the MANUAL mode where you have to provide the Alexa Skill ID if you want direct access from the Convoworks Admin Panel to the Store Preview of your Alexa Skill. You also have to catch intents manually using the Platform Intent Reader.

The second one, the AUTO mode, is the one where the Alexa Skill Management API allows you to manage and test your Alexa Skill in Convoworks Test Panel with Amazon NLP delegate selected. It also enables service propagation. Considering its advantages, we recommend using the AUTO mode.

Set the Mode to AUTO. Once you configuration was created on Auto mode, you’ll no longer have the ability to switch back to MANUAL mode. This behavior also applies when you change from MANUAL to AUTO and save the platform config.

Steps for configuring the AUTO mode of General Configuration:

  • Enter Alexa skill‘s invocation
  • You can leave the Service ID field empty. The skill will be created and the data filled automatically. If you fill in the Service ID data,  Convoworks will try to retrieve information on the skill
  • Select another Interaction Model Sensitivity option if you want your skill model to respond to more user requests with the Fallback Intent.
  • Enable Auto Display if you want to display text spoken by Alexa on devices that have a display
  • Enable or disable Alexa Interfaces

Steps for configuring the AUTO mode of Amazon Alexa Skill Account Linking:

Make sure you check the Enable Account Linking for Alexa Skill checkbox.

Fields ready to be filled for Account Linking of an Alexa Skill:

  • Enable Account Linking – Enable Account Linking for the selected Alexa Skill. When disabled, other fields are hidden.
  • Skip Account Linking on Skill Enablement – Should the user be forced to link the account before the skill can be enabled?
  • Your Web Authorization URI * – The URI where customers will be redirected in the companion app to enter login credentials. This field is required.
  • Access Token URI * – This URI will be used for both access token and token refresh requests. This field is required.
  • Your Client ID * – Unique public string used to identify the client requesting for authentication. This field is required.
  • Your Secret * – A credential you provide that lets the Alexa service authenticate with the Access Token URI. This is combined with the Client ID to identify the request as coming from Alexa. This field is required.
  • Scope – The list of permissions to request from the skill user. You can provide up to 15 scopes. Separate list items with a semicolon (;),. This field is optional.
  • Domain List – The list of domains that the authorization URL will fetch content from. You can provide up to 30 domains. Separate list items with a semicolon (;). This field is optional.

Additionally, you can click the Get existing Account Linking Information of existing Alexa Skill to get the account linking state of your existing Alexa Skill.

Account Linking Examples

Link Amazon User Accounts with your Alexa Skill

  • Values that are required to be set in Amazon Alexa Skill Account Linking Section
    • Your Web Authorization URI https://www.amazon.com/ap/oa
    • Access Token URI https://api.amazon.com/auth/o2/token
    • Your Client ID – from your security profile, has to be entered to satisfy the API requirements
    • Your Secret – from your security profile, has to be entered to satisfy the API requirements
    • Scope – scope for LWA is required and can be all of these below:
      • profile
      • profile:user_id
      • postal_code
  • Action required to be taken on your Amazon Security Profile
    • Copy the Alexa Redirect URLs from [Alexa Developer Console] > [tools] > [account linking] > [Alexa Redirect URLs]
    • Add all of the Alexa Redirect URLs to[your security profile] > [Allowed Return URLs]  in [Alexa Developer Console]>[click on your user icon] > [settings] > [Login with Amazon] > [Security Profiles] > [Select Your Security Profile from list] > [Web Settings] > [Allowed Return URLs]

Link Convoworks Admin Accounts with your Alexa Skill

  • Values that are required to be set in Amazon Alexa Skill Account Linking Section
    • Your Web Authorization URI * – https://proto.convoworks.com/login/amazon or https://proto-stage.convoworks.com/login/amazon
    • Access Token URI * – https://proto.convoworks.com/rest_public/proto/v1/token/amazon or https://proto-stage.convoworks.com/rest_public/proto/v1/token/amazon
    • Your Client ID * – your client id, has to be entered to satisfy the API requirements
    • Your Secret * – your client secret, has to be entered to satisfy the API requirements

Link other User Accounts with your Alexa Skill

  • Values that are required to be set in Amazon Alexa Skill Account Linking Section
    • Your Web Authorization URI * – https://www.example.com/login
    • Access Token URI * – https://api.example.com/auth/o2/token
    • Your Client ID * – your client id, has to be entered to satisfy the API requirements
    • Your Secret * – your client secret, has to be entered to satisfy the API requirements
    • Scope – scopes if they are required for your OAuth service

 

Steps for configuring the AUTO mode of Distribution Information:

If you have already a skill on Alexa that has entered information about the distribution, you can tap the [Get existing Distribution Information of existing Alexa Skill in (default-locale)]. This will pre-fill the fields and you are able to save the config and propagate it to Amazon.

Distribution Configuration of Skill Store Preview

This section is responsible for configuring the store preview of an Alexa Skill.

This is the Distribution section on the Alexa Developer Console for a skill that is ready for publishing.

The publishing information of an Alexa Skill can be edited in this section.

Steps to edit Skill Store Preview for supported locales:

  • Public name – display name of the skill, when you create a new service, this field is pre-filled and is required
  • One sentence description – short description of the skill, when you create a new service, this field is pre-filled and is required
  • Detailed description – more details of your skill, when you create a new service, this field is pre-filled and is required
  • What’s new – describe your latest features if you have some, this field is optional
  • Small Skill Icon – it has to be a 108×108 png, if the image is not provided, the default will be used from https://via.placeholder.com/108.png/09f/fffC/O as a placeholder, this field is required for skill certification
  • Large Skill Icon – it has to be a 512×512 png, if an image is not provided, the default will be used from https://via.placeholder.com/512.png/09f/fffC/O as a placeholder, this field is required for skill certification
  • Category – select a category, when selecting a child-related category, the answer to the question ‘Is this skill directed to or does it target children under the age of 13?’ will be set to yes
  • Keywords – keywords under which your skill will be displayed in the Alexa skill store
  • Privacy Policy URL – mandatory when performing skill validation before submission, otherwise the validation will fail
  • Terms of Use URL – your Terms of Use URL

This section relies on the Service Meta.

Distribution Configuration of Skill Privacy and Compliance

This section is responsible for configuring the Privacy and Compliance of an Alexa Skill.

This is the Privacy and Compliance section on the Alexa Developer Console for a skill that is ready for publishing.

The Privacy and Compliance of an Alexa Skill can be edited in this section.

This section relies on the Service Meta.

Basically, answer accordingly to the questions provided in this section. Also, provide testing instructions on how the Alexa Skill reviewer can interact with your skill.

Currently, for custom skills that are child-directed, the validation will fail and you’ll have to go here to resolve that issue.

Test your propagated Alexa Skill

After you have successfully propagated your changes to Amazon Alexa, just enable your skill to use in your Alexa companion app or enable it on the Test tab in Alexa Developer Console.

Steps to enable skill to test in Alexa Companion App:

  1. Open your App
  2. Tap More in the navigation
  3. Tap Skills & Games
  4. Tap Your Skills
  5. Scroll right to Dev on the panels below the tabs
  6. Tap on Dev
  7. Search for your skill
  8. Tap your skill and hit the ENABLE TO USE button
  9. Open the recently enabled skill on your Alexa device by invoking it.

Steps to enable skill to test in Alexa Developer Console:

  1. Login to your Alexa Developer Console
  2. Click on the Search by skill name or skill ID to find your skill
  3. Open the found skill and click on the Test tab.
  4. Make sure that the Skill testing is enabled in Development.
  5. Open the recently enabled skill on your Alexa device by invoking it.

Final Notes

After you have filled out all of the fields hit the Create button to save the configuration and Convoworks will trigger the Alexa Skill Management API to create your Alexa Skill with all of the default intents and additional intents you have specified and intents from enabled interfaces

Now you’ll be able to propagate your Intents defined in Convoworks, Account Linking for an Alexa Skill, and the Skill Distribution Information to Alexa Developer Console. Make sure you catch the intents in the Workflow with Convoworks Intent Reader

To verify that the propagation was successful, go to your Alexa Developer Console and take a look at your recently created Alexa Skill.

Was this article helpful to you? Yes No

How can we help?