Basic Workflow
The workflow (described in Architecture Overview) begins when a user says a phrase, such as “Play [media title],” to the multimodal device. Alexa’s natural language processing intelligence does the work of parsing the user’s utterances and figuring out the user’s intent. Alexa then packages up the user’s intent into a directive. The following directives are used with multimodal device interactions:GetPlayableItemsGetPlayableItemsMetadataGetBrowseNodeItemsGetDisplayableItemsGetDisplayableItemsMetadataGetBrowseNodeItemsGetNextPage
GetPlayableItems directive to the appropriate Lambda functions for those catalogs. The GetPlayableItems directive looks like this:
Alexa Request: GetPlayableItems
header block. You can see that this is a GetPlayableItems directive.
Your Lambda receives this directive as an event. Your Lambda code needs to perform whatever lookups are necessary to identify what media titles match that request (based on the payload in the directive). As part of the lookup, your Lambda might identify additional media titles relevant to the user’s request.
Then your Lambda returns a response to Alexa that conforms with the requirements for responses for that directive type. For GetPlayableItems directives, the GetPlayableItemsResponse looks like this:
Lambda Response: GetPlayableItemsResponse
mediaIdentifier values matching the user’s request. The values for these mediaIdentifier properties correspond with the content IDs in your catalog.
After Alexa receives the GetPlayableItemsResponse response, Alexa might ask the user to clarify which media title the user wants to play, or which video provider the user wants to play the media from (in cases where multiple providers have the same media).
After resolving the media the user wants to play, Alexa will then send another directive to your Lambda called GetPlayableItemsMetadata. This directive asks your Lambda for more details about the chosen media title. Alexa needs this in order to show information about this media title (the value for the mediaIdentifier — for example, recordingId://provider1.dvr.rp.1234-2345-63434-asdf — means nothing to Alexa). You need to supply information related to this mediaIdentifier that indicates what to show on the user’s screen, such as the title, thumbnail, duration, rating, etc.
The GetPlayableItemsMetadata that Alexa sends might look like this:
Alexa Request: GetPlayableItemsMetadata
payload identifies a specific mediaIdentifier that the user wants to play.
Your Lambda then retrieves the needed information about this mediaIdentifier and returns a GetPlayableItemsMetadataResponse response with more information about it. The response might look as follows:
Lamba Response: GetPlayableItemsMetadataResponse
playbackContextToken to your web player, which then converts this identifier into a media playback URL and loads the media.
An Analogy of the Interaction
To put this interaction more concretely, consider this analogy. A customer walks into a video store and asks the clerk, “I want to watch To Kill a Mockingbird.” The clerk passes on the request to a backroom worker who looks through the media library and locates the Mockingbird media section. He finds that there are multiple matches for this media, with different editions and variations, some matches with Gregory Peck and other matches with Mockingjay in Hunger Games. The backroom worker relays the info back to the clerk, who then asks the customer, “Which of these media titles do you actually want?” The customer says, “I want the first one (with Gregory Peck).” The clerk then turns to the backroom worker and says the customer wants the Gregory Peck media title. The backroom worker retrieves all the details about the Gregory Peck title and returns this info to the clerk. The clerk loads the media into a player and plays it for the customer. In short, the user’s request gets converted to aGetPlayableItems directive sent to your Lambda. Your Lambda responds with a GetPlayableItemsResponse listing the matching titles. Alexa replies with a GetPlayableItemsMetadata directive for the title the user selects, and your Lambda replies with a GetPlayableItemsMetadataResponse containing all the details for playback.
Exactly how you code your Lambda and perform the necessary backend services to retrieve the right data is up to you. The documentation here will not provide tutorials that describe how to interact with your backend services to gather and generate the needed responses because each partner’s code and backend services differs, as these backend services differ considerably from partner to partner.
Stepping Section by Section through the Sample Lambda
The following sections will explain the logic in the sample Lambda function. The sample Lambda function, provided in Step 1: Create Your Video Skill and Lambda Function, specifically the section Step 1.3: Create the Lambda Function for Your Video Skill, tries to demonstrate the required responses for several directive types. Let’s unpack the Lambda function section by section. Also, note that you can provide your Lambda code in a variety of languages. See the following AWS Lambda documentation topics for instructions on working with other languages:- Building Lambda Functions with Node.js
- Building Lambda Functions with Python
- Building Lambda Functions with Ruby
- Building Lambda Functions with Java
- Building Lambda Functions with Go
- Building Lambda Functions with C#
- Building Lambda Functions with PowerShell
Section 1 Explanation
handler method is explained in AWS Lambda Function Handler in Node.js. When a Lambda function is invoked, AWS Lambda starts executing your code by calling the handler function. AWS Lambda passes any event data to this handler as the first parameter. The runtime passes three arguments to the handler method: event, context, and callback:
event: The first argument is theeventobject, which contains information from the invoker. In this case the invoker is the Alexa directive. Alexa passes this directive as a JSON-formatted string when it callsInvoke.context: The second argument is thecontextobject, which contains information about the invocation, function, and execution environment.callback: The third argument,callback, is a function that you can call in non-async functions to send a response. Thecallbackfunction takes two arguments: an Error and a response. The response object must be compatible withJSON.stringify.
event and context, you can log these to the console:
event is logged as part of the hardCodedResponse function; the context isn’t logged at all in the sample Lambda.
The event and context are JSON objects. JSON.stringify renders a JSON object as a string. The JSON.stringify method takes several parameters: the object, a replacer (not used here), and a spacing value.
The context isn’t necessarily important here, but it shows the name of the Lambda function invoked, the log stream, the memory used, and other details. In Cloudwatch, the context for an event in our workflow looks as follows:
hawaii_echo_lambda is the Lambda invoked, and logs in Cloudwatch are grouped in /aws/lambda/hawaii_echo_lambda.
After this initial handler method, the hardCodedResponse(event, context); function runs, taking in the event and context as parameters. This function is explained in the next section.
Section 2 Explanation
hardCodedResponse that passes in the event and context as parameters. This shows how you can get information from the incoming event (the Alexa request) and set variables for the information contained in that event.
For example, the sample Lambda code sets a variable called name to store the value for event.directive.header.name.
As needed, you can set any properties in the directive to some variable that you use in your lookups. The information you need (and how you manipulate it) depends on the task you’re trying to perform. For example, you might want to perform a lookup based on a movie title. As such, you might need certain details to feed into your lookup functions with your backend services.
Section 3 Explanation
At this point, the sample Lambda code simply defines variables for the pre-defined responses that it will respond to the directive with. For example:Section 4 Explanation
GetPlayableItems, then the GetPlayableItemsResponse is passed back to Alexa in the callback. The context.succeed method puts the information into the callback.
In the Cloudwatch logs, look for a line that begins with Lambda Response to see the response that your Lambda sends back to Alexa.

