Alexa Content Skill with Media in APL Mode

(Audio, Video, & Images)

Objective

This document will show you how to create skills with APL (Alexa Presentation Language) capability and consume them from devices like the Echo show that can present such skills.

Introduction to APL

With Alexa Presentation Language (APL), you can create visual experiences to accompany your skill. Users can see and interact with your visual experiences on supported devices such as the Echo Show, Fire TV, some Fire tablets, and other devices. You can include animations, graphics, images, slideshows, and video in your visual experience.

Goal

The VoiceWorx platform can define APL skills (video, audio and image) for consumption in an external device with capability to interpret and present these media types. To demonstrate this ability, we will upload video content and define an Alexa skill intent that can be invoked to display this video via APL.

Our goal is to demonstrate the capability of users to define media content via APL response to intent requests from devices that have the capability to display those content types with appropriately formatted APL response data. We will create an Alexa Skill named APLVideo. This skill will define a PlayVideo intent that retrieves and plays video content stored/defined in the VoiceWorx platform via APL.

Steps

The following shows the general steps/activities that will be carried out in setting up this integration. Note: It is advisable to use same email for signup across the 3 channels below. Step 1 -3 below are compulsory.

  1. Sign up for Alexa account

  2. Sign up for Alexa developer account.

  3. Sign up for VoiceWorx platform

  4. Ensure you Login With Amazon (LWA) https://developer.amazon.com/alexa/console/ask account is setup by your admin. If you are the account admin, you can follow this instruction to set it up.

  5. Set up connection to the external web API

  6. Create a custom skill in Voiceworx.

  7. Publish the skill

  8. Test the Alexa skill.

Set up connection to the external web API

  1. Login to the VoiceWorx platform, use left navigation menu and click “Integration” then select “Connect System”. In the resulting page, click “Connect External Systems”.

  1. Select “Custom” as Integration Category, Select “Internal Content” as SystemType. Provide a System Instance Name, we are using “APLVideo” as instance name. Click on Connect System after filling up the details.

Integration Category: Custom

System Type: Internal Content

System Instance Name: APLVideo

Upload Content in VoiceWorx Platform

  1. Login into the VoiceWorx platform, using the left navigation menu click “Content” then select “Content Categories” then click “Add New Category”.

  1. In the “Add New Content Category” pop up box enter the following:

Content Category: APLVideo (Remember this name for Step 25)

Description: APLVideo

Click: Add

  1. Use left navigation menu and click “Content” and select “Content”.

  1. You can now create content in two ways:

  2. Add New Content

Users can upload their own Html, SSML and media files to create contents.

  1. Create Content from Template

Allows users to create a content using inbuilt Content Templates provided by VoiceWorx.

  1. Click “Add New Content” button.

Perform the following activities to add new content.

    • Content Name: Test Video

    • Content Code: Test Video

    • Category: APL Video

    • Text: Test Video for APL Content

    • Media: Check box and select the Media type

    • Media Type: Video

    • Media Source: Upload File or Media URL. Select Media URL if you have a publicly accessible media source, else you can select a video file on your machine. For demo purpose here, we are uploading file from local device.

    • Upload File: If you choose to Upload File, you shall be able to Upload File.

    • Media URL: If you select to provide Media URL, the URL that you provide here shall be publicly accessible. You can provide the following sample data if you want to create content using Media URL. (URL: https://demovideo.s3.amazonaws.com/demo_video.mp4)

    • Click: Fill details as shown below and click on Add.

  1. Return to left navigation menu and select “Content” then select “APL Content”. Then click “Add New APL Content”.

  1. Once in “APL Content” the user will upload a predesigned APL JSON file by filling in the fields listed below. User can either upload a APL JSON file or provide a publicly available URL for a sample APL Document.

  2. For this exercise we will use a sample APL document we have uploaded in this publicly available URL. Please select or enter the information into the following fields:

Name: APLVideoDocument

Content Type: Document

Category: APLVideo

Enter Description Text: Sample skill APL design document

APL Json file Source: Click Upload JSON File

Json URL: (need to update this, proceed with file provided for now) https://voiceworxstorage.blob.core.windows.net/documents/DefaultAPLContent.json

Click: Add

Create Custom Skill in Voiceworx.ai

  1. To create a custom skill use left navigation menu and select “Custom Skills” then select “Manage Skill”. Then click “Create New Custom Skill”.

  1. Please select or enter the information into the following fields:

Name: APLVideo

Custom Skill Type: Search

Category: None

Click: Save

  1. In the top menu tabs, select “Data Sources” then select “Create New Data Source”. Enter or select the following information:

Name: APLVideoDS

Integration Configuration: Internal Content: APL Video

Click: Save

  1. In the top menu tabs, select “Methods” then select “Create New Methods”. Then, in the sequence of tabs, provide the following inputs to setup the method.

Method Name: PlayVideoMethod

Request Type: Content

Content Name: {{Video Name}}-Test Video

CategoryName: APLVideo

Empty Result Template: Video not found

Result Option: Click No Media: Enable Alexa Presentation LanguageClick the bar to open additional options then select Enable APL

APL Document: APLVideoDocument

APL Data Json Path: $.[*]

APL List Item JSON Path: $.records[0]

Empty Result APL Definition : VideoAPL

Click: Save and Test

  1. Before moving to another step, let’s test whether the method is working fine or not. Click on the ‘Test’ button in the newly created method.

For Test purpose, you need to fill out the parameters. In our case, we have one parameter {{Video}} for ContentName. Fill the following details:

Video: Native Video (This name shall match with that of the content created in Step 17).

  1. In the resulting test screen select or enter the following:

Test Method: APL Video then GetVideo

Request Type: Content

Result Template: None

Empty Result Template: Video not found

Parameters ContentName: Test Video

Note: “test video” is the name of the content we uploaded in Step 19 above.

Click “Method Test” after inserting the values, click “Result” then “Result Test”.

  1. In the top menu tabs, select “Intents” and “Create New Intent”. Then select or enter the following:

Name: PlayVideoIntent

Intent Type: Search

Intent Action: Execute Method

DataSource: APLVideoDS

DataSource Method: PlayVideoMethod

Click: Save

  1. Now you want to create Slots. Slots correspond to the parameter that you want to use in your app. In the top menu tabs select “Slots” then select “Create New Slot”. Note the re-prompt message is what Alexa will ask if it can’t fill/resolve the video slot.

Name: Video

Slot Order: Blank

Reprompt Message: which video

Type: Test

Custom App: APLVideo

Intent: PlayVideoIntent

Click: Save

  1. After creating slots, now you have to create utterances. Utterances are words spoken to launch specific intents. In the top menu tabs select “Utterances” then select “Create New Utterance”.

Value: Show video

Custom Skill: APLVideo

Intent: PlayVideoIntent

Click: Save

  1. In the top menu tabs, select “Input” and select “Create New Input”. Then input or select the following:

Provide following in the form to create input.

Name: PlayVideoInput

Description: Blank

Custom Skill: APLVideo

Custom Intent: PlayVideoIntent

Data Source: APLVideoDS

Data Source Method: PlayVideoMethod

Click: Save

Publish to Alexa

  1. In the top menu tabs select “Publish” then click “Add Skill Publishing”.

External Skill Name: This will be the name of the skill in Alexa. Therefore, make it unique and different from the names of your other skills in Alexa. In this case we named it “APLVideo”.

Skill Type: Search

Channel: Alexa

Ensure the following are not checked: Require Account Linking & Auto Publish

External Skill ID: (This information will automatically drop in this field).

Skill Invocation: this will be what users say to launch your skill in Alexa. It must be in lower case alphabets cannot contain START, BEGIN, STOP, EXIT, LAUNCH and cannot contain number or special characters. For this step we used “APL Video”.

Welcome M

essage: Welcome to APL Video Test. How can I help you?

Reprompt Message: You can say “play video, APL video” or say “help” for more guidance. How else can I help you?

Help Message: You can ask me to play a video, by saying play video, APL video. To exit APL video, say exit.

Goodbye Message: Thank you for using APL Video, goodbye.

Fallback Message: I am sorry I didn’t understand that. How else can I help you?

Optional: Replace all placeholder values in all “Message”

Uncheck: Enable Address, Full Address, Region & Postal Code, etc. (Settings shown in the images below).

Enable APL Support: Check

Select Default APL Content: APLVideoDocument

Click: Save

  1. On the resulting screen click “Publish To Alexa”.

  1. Select your login with Amazon profile then click “Publish To Alexa”.

Then enter or select the following options:

Selected Skill: APLVideo

Select Amazon Account (LWA)

If you do not have an Amazon Account for LWA, click on the “Add Amazon Account for LWA” to set up. Select the LWA account setup by your admin and

Click: Publish To Alexa

  1. On the resulting screen, ensure that a success message shows for the publishing steps before clicking “Go To Alexa Skill”. If success message does not appear, go back to Publishing to fix any issue shown in publishing result.

  1. On the Alexa skill page, ensure “Full Build Successful” message appears in bottom right corner before starting to test skill.

  1. After the skill is successful, in the interface tab, you want to make sure that Alexa Presentation Language has been checked.

  1. At the top of the page click “test” tab and change the skill test status to from “Off” to “Development”

Enable Skill

  1. Go to https://alexa.amazon.co.uk/spa/index.html#cards

  2. Select “Skill” on left navigation menu, then select “All Skill”.

  1. Select “APLVideo” skill and click “Enable”.

Echo Show Set Up

  1. To setup your Echo Show follow this tutorial from Amazon.

  2. To ensure that Echo Show language is set to English US.

Please select or enter the following:

Slide down the top downward pointing arrow button in Echo Show

Click: Device Option

Select: Device Language

Ensure its on English (US)

Invoke the skill in Echo Show by Saying “Alexa open APL Video Test” or “APL Test”

  1. Play video skill by saying “show video”.

Note: APL was the content name for the video we set up in the steps above.

Congratulations! You have successfully completed building

Alexa Content Skill with Media in APL Mode.

Note: App and skill are interchangeably used in the document.

PreviousQ&A App with publishing to AlexaNextAlexa Content Skill with Media in Native Mode

Last updated