Handling the Action Request

Once Alexa has gathered all of the information required for the dialog, the scheduleTrip() action is invoked, sending the trip data to fulfillment code for processing. The good news is that writing fulfillment code to handle action processing is very much the same as fulfillment code we’ve written before to handle intent requests. But rather than checking for a request type of IntentRequest in the handler’s canHandle() function, we need to check for a request type of Dialog.API.Invoked, like this:

As you can see, the structure of this canHandle() function is very much like that of other canHandle() functions we’ve written, except that it returns true if the request type is Dialog.API.Invoked and if the request’s apiRequest.name property is “com.starport75.scheduleTrip”—the fully-qualified name of the action in our conversation model.

Although this approach to writing a canHandle() function for an action request is pretty straightforward, if you created your Alexa skill from scratch using the “Weather Bot” template, you can instead take advantage of a helper function that comes in the project’s util.js module. A slightly simpler form of canHandle() will look like this, using the isApiRequest() function:

Now, assuming that the canHandle() returns true, then it means that our fulfillment code has received an action request for the scheduleTrip action. We’ll need to handle that action request in the handle() function:

As you can see, this handle() function pulls the destination and trip dates out of the request. But it does it a little bit differently than we’ve seen before. All action arguments are available in the request as API arguments and can be obtained using the getApiArguments() function from the util.js module. That’s precisely what this handle() function does for the departure and return dates.

The same would work for the destination, too. But since the destination is a custom list type, the destination API argument will contain the unresolved entity value and not the fully resolved value. If the user planned a trip to “the red planet”, then the destination argument would contain the text “the red planet”. It’s the “Mars” value we need, so it’s better to fetch the value as a slot instead of as an API argument.

After the trip is scheduled by calling the scheduleTrip() function, the handle() function returns the action response. Unlike intent handlers, API request handlers do not return a response created with the response builder. Instead, they simply return an object containing data to be given to the APL-A template associated with the action (scheduleTrip_apla/document.json in this case).

Just like any other request handler in an Alexa skill, you’ll need to be sure to register the API request handler with the skill builder:

Now we’re ready to deploy and try out this new Conversations-based skill.