We’ve changed our name! API.AI is now Dialogflow. Learn more here.

Alexa Importer

Introduction

This guide will walk through the full process of importing a simple Alexa skill into a Dialogflow agent.

Before you begin, download the accompanying sample at fulfillment-importer-sample via ZIP download or clone the Git repository. This sample skill responds to user queries for popular videos by telling the user the titles of the 5 most popular YouTube videos in the US at the time.

Setting Up and Importing

  • Click Integrations in the left menu and then click the Amazon Alexa tile.

  • In the dialog that appears, click the Import from Alexa button.

  • Select the speechAssets.zip file found under skill/speechAssets/ in the file you downloaded. The IntentSchema.json and SampleUtterances.txt files will be imported by Dialogflow to define your Dialogflow agent.

Explore the Dialogflow Agent

Now you can see all your Alexa skill intents have been imported into Dialogflow as Intents.

All of the examples in from the SampleUtterances.txt file are now listed in their corresponding Dialogflow intent under "User says".

Next, you'll modify your existing fulfillment to work with Dialogflow's webhook fulfillment.

Modify your fulfillment

Dialogflow sends a HTTP POST request to your webhook fulfillment URL with JSON data about the request. In the case of the popular videos example, you only need information about the intent that was matched and the action that is requested. Dialogflow has created the concept of an action which can be defined for each intent.

Actions are used to identify what collection of tasks need to be performed to fulfill the user's request. Dialogflow's importer created an action for each intent that matches the name of the Popular Video's skill intent. The action name is sent in every webhook request from Dialogflow. All this means is you can inspect each request from Dialogflow for the action name and use that action name to call the function of the same name to get the needed fulfillment and response.

For the Popular Videos example the GetPopularVideosIntent intent in Dialogflow has an action associated with it named GetPopularVideosIntent. The name of the action is sent in Dialogflow webhook request in the result attribute as seen below:

{
  "result": {
    "action": "GetPopularVideosIntent",
 ...

Our webhook will receive this request, and then call the function with the same name as the action, in this case, GetPopularVideosIntent. The GetPopularVideosIntent function will perform all the necessary fulfillment steps and construct a response as it did fulfilling the skill. Our new fulfillment will take this response and respond to the initial HTTP request initiated by Dialogflow with the contents of our response.

Replace Alexa library with Firebase Functions library

For this example, you will be using Cloud Functions for Firebase to host our fulfillment, which will allow our Dialogflow agent to send a request to our Cloud Function's URL. While you will be deploying to Cloud Functions for Firebase in this guide, you can use any hosting service or tool that will allow this code to be triggered by a request to a HTTPS URL.

Replace this:
const Alexa = require('alexa-sdk');        
      
With this:
const functions = require('firebase-functions');        
      

Replace the request handler

You'll now need to create a new request handler to handle requests sent to Cloud Functions for Firebase. To do this, replace this code:

Replace this:
exports.handler = function(event, context, callback) {
  var alexa = Alexa.handler(event, context);
  alexa.APP_ID = APP_ID;
  alexa.registerHandlers(handlers);
  alexa.execute();
};        
      
With this:
exports.popularVideos = functions.https.onRequest((req, res) => {
  const handler = new Handler(handlers);
  handler.run(req, res);
});       
      

This removes the Alexa request handler and uses a new event handler that you will define next by adding:

// Define new Handler class to reuse previously defined handlers
class Handler {
  constructor(handlers) {
    this.handlers = handlers;
  }
  emit(event, data) {
    if (event.startsWith(':')) {
      this.res.json({
        speech: data,
        displayText: data
      });
      return;
    } else {
      this.handlers[event].call(this, data);
    }
  }
  run(req, res) {
    this.req = req;
    this.res = res;
    this.emit(req.body.result.action);
  }
}

This handler allows you to reuse your previous intent handlers while providing compatibility with requests from your Dialogflow agent. Due to the way Dialogflow imports Alexa skills, the name of the intent handler has a corresponding action name in Dialogflow. This action attribute is sent in the request body from Dialogflow in the result.action JSON attribute. The run method calls the function in the handler object that has the same name as the value in the result.action JSON attribute in the body of the request coming from Dialogflow. This calls the correct intent handler. When the intent handler is called, the handler with either call another intent handler or emit a response. The Handler Class' emit method captures this response and sends it back to the user as a HTTP response to Dialogflow's request. This response is then sent to the user.

Next, you'll also need to modify your package.json file to remove the Alexa library dependency and add the Firebase functions dependencies.

Replace this:
"dependencies": {
  "alexa-sdk": "^1.0.6"
}
      
With this:
"dependencies": {
  "firebase-functions": "^0.5.9",
  "firebase-admin": "5.0.0"
}
      

And lastly run npm install to install all the dependencies.

Deploy your new fulfillment

For this section you can either use the function you edited in step 1 or use the functions folder found in the dialogflow directory in the sample repository. If you use you code from step 1, you'll need to put the index.js, package.json and dependencies (node_modules) in a folder called functions.

Setup Firebase and Cloud Functions

Follow the instructions to set up and initialize Firebase SDK for Cloud Functions. Make sure to select the project that you have previously generated in Dialogflow's console and to reply N when asked to overwrite existing files by the Firebase CLI.

Deploy your code

Run firebase deploy --only functions and take note of the endpoint where the fulfillment webhook has been published. It should look like Function URL (yourAgent): https://${REGION}-${PROJECT}.cloudfunctions.net/yourAgent

Add fulfillment URL to Dialogflow

Go to your newly created Dialogflow agent and select Fulfillment in the left column, click the switch to enable webhook fulfillment for your agent, and then paste the URL to the Firebase function you just deployed in the URL field.

Next go to the Intents that require fulfillment and make sure the Use webhook box is checked and click save:

Go ahead and try your agent with the built in simulator on the right!

Your agent is now ready to be deployed to all of Dialogflow's integrations like Slack, Facebook Messenger and over a dozen more messaging and voice platforms. The next sections walk through two examples: deploying to Actions on Google to make apps for the Google Assistant and redeploying it back to Alexa.

Making your agent compatible with Actions on Google

First, you need to make a few configuration changes to your agent. The first interaction with Actions on Google is triggered by a welcome event. You need to map your Welcome intent to the correct action in your fulfillment. To do this open the Default Welcome Intent and change the Action from input.welcome to LaunchRequest. This will trigger the LaunchRequest intent handler in the fulfillment and return the correct response. Since this is the only action your agent can perform, you need to click on Actions on Google and check the End conversation box to cause the conversation with the user to end after this intent is matched. All the configurations can be seen below:

Testing your agent

To make your agent accessible to Google Assistant users on their phones and Google Home, go to Integrations tab on the left and click the switch to enable Actions on Google.

Next click Test and then View to try out your agent on the Actions on Google simulator:

In the simulator click Start and type Talk to my test app in the prompt. You should see your agent's response as indicated below!

This Assistant app will work on all devices logged into the same Google account, so you can try your Assistant app on your Google Home or Android phone. To deploy publicly to all Google Assistant users, follow the publishing instructions on the Actions on Google developer site.

Redeploying your Skill

Along with creating an agent that works with the Google Assistant and dozens of other platforms, you can export your agent back to Alexa as well. While Alexa uses its own natural language processing, exporting back to Alexa will also include any alterations and training data from Dialogflow. Dialogflow's training data is stored in Dialogflow as user says examples for each intent. Every user says example for each intent is exported to Alexa's Sample Utterances to allow Alexa to better match user's requests. This means your agent will have a similar user experience between platforms and improvements and training of your agent will be shared across platforms.

To deploy back to Alexa, go to Integrations tab on the left and click the Alexa integration tile.

Next click on the Export for Alexa button.

A zip file will begin downloading. Once it's complete, unzip it and find the IntentSchema.json and SampleUtterances.txt files.

Next, go to https://developer.amazon.com/edw/home.html/skills to view all your skills.

Select the skill you'd like to export to by clicking on the skill name for the corresponding skill:

On the left select "Interaction Model" from the list and you should see the screenshot below:

Copy the contents of the IntentSchema.json file and paste it into the editor under the "Intent Schema" section.

Next, copy the content of the SampleUtterances.txt file and paste the contents into the editor on the "Sample Utterances" section.

For information about exporting to Amazon's Custom Slot Types please see our Alexa Exporter documentation.

What's next?

More integrations!

Now that you have your Dialogflow agent as the canonical source for your conversational app, you can deploy to more integrations like Slack, Facebook Messenger and other messaging and voice platforms as well as use Dialogflow's SDKs or API to integrate your conversational app into your own apps and tools.

Train and improve your Dialogflow agent

Use Dialogflow's training to improve your agent. You can also improve your user's conversational experience with rich messaging, context for conversation state and branching control, parameters and entities to extract data from your user's responses. Dialogflow also includes analytics to see how your changes and additions affect your agent's performance. Also, don't forget to redeploy to Alexa after you've made changes to your Dialogflow agent!