VoiceWorx.ai
Search
⌃K

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. 1.
    ​Sign up for Alexa account​
  2. 2.
    ​Sign up for Alexa developer account.
  3. 3.
    ​Sign up for VoiceWorx platform​
  4. 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. 5.
    Set up connection to the external web API
  6. 6.
    Create a custom skill in Voiceworx.
  7. 7.
    Publish the skill
  8. 8.
    Test the Alexa skill.

Set up connection to the external web API

  1. 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. 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. 1.
    Login into the VoiceWorx platform, using the left navigation menu click “Content” then select “Content Categories” then click “Add New Category”.
  1. 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. 1.
    Use left navigation menu and click “Content” and select “Content”.
  1. 1.
    You can now create content in two ways:
  2. 2.
    Add New Content
Users can upload their own Html, SSML and media files to create contents.
  1. 1.
    Create Content from Template
Allows users to create a content using inbuilt Content Templates provided by VoiceWorx.
  1. 1.
    Click “Add New Content” button.
Graphical user interface, application Description automatically generated
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. 1.
    Return to left navigation menu and select “Content” then select “APL Content”. Then click “Add New APL Content”.
  1. 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. 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. 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. 1.
    Please select or enter the information into the following fields:
Name: APLVideo
Custom Skill Type: Search
Category: None
Click: Save
  1. 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. 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. 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. 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”.
Now, Click on Method Test, then Result tab in the Test Result section. Click on Result Test button. If your Result Test displays the URL of the content file, then your Method creation succeeded. If you receive any other response than the one shown below, you might want to go through the steps in the document to ensure that none of the steps have been missed.
​
  1. 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. 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. 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. 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. 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. 1.
    On the resulting screen click “Publish To Alexa”.
  1. 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. 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. 1.
    On the Alexa skill page, ensure “Full Build Successful” message appears in bottom right corner before starting to test skill.
  1. 1.
    After the skill is successful, in the interface tab, you want to make sure that Alexa Presentation Language has been checked.
  1. 1.
    At the top of the page click “test” tab and change the skill test status to from “Off” to “Development”
Enable Skill
  1. 1.
    Go to https://alexa.amazon.co.uk/spa/index.html#cards​
  2. 2.
    Select “Skill” on left navigation menu, then select “All Skill”.
Graphical user interface, text, application Description automatically generated
  1. 1.
    Select “APLVideo” skill and click “Enable”.
A screenshot of a cell phone Description automatically generated
Echo Show Set Up
  1. 1.
    To setup your Echo Show follow this tutorial from Amazon.
  2. 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”
A screen shot of a computer Description automatically generated
  1. 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.
Skills - Previous
Q&A App with publishing to Alexa
Next - Skills
Alexa Content Skill with Media in Native Mode
Last modified 2yr ago