Deploy your Assistant app fulfillment webhook using Cloud Functions for Firebase.

TL;DR If you’re building an Assistant App, Cloud Functions for Firebase is a great choice to implement fulfillments for your conversation webhooks. Let’s see why!

The Actions on Google platform lets you build actions that allow users to get things done on Assistant surfaces such as Google Home, Android phones, or iOS phones. One of the coolest thing about it is that you don’t need to write any platform-specific code for the individual clients. You just focus on designing your conversation with the user and implement it as an HTTPS web service, along with the logic for your app.

You can implement the HTTPS web service using the language and the platform of your choice, but I’m gonna talk about how using Cloud Functions for Firebase will make your life easier.

Cloud Functions for Firebase lets you automatically run backend code in response to events triggered by Firebase features, and more interesting for us, HTTPS requests. The code you write is stored in Google’s cloud and runs in a managed environment, and there’s no need to manage and scale your own servers.

Tell more about it!

In my opinion the top reasons to use Cloud Functions for Firebase to build your Assistant apps are:

• When you create a project on the Actions on Google console, that project becomes also visible in the Firebase Console, so no need to manage yet another project.
• Functions are allowed to use node.js modules, which means you can use our Actions on Google client library for Node.js for the smoothest Developer Experience.
• You can deploy and run functions locally using the Firebase CLI, to test your functions before deploying to production. Note that for end-to-end testing using the Actions on Google simulator, you need to use a secure tunneling solution to expose the function running on your local machine.
• Cloud Functions for Firebase provides a free tier without the need to provide payment information, allowing you to try our samples and tinker with your ideas quickly and easily. Note that the free tier allows outbound network requests only to Google-owned services.
• You can benefit from the integration with the other services offered by Firebase. For example you can use Firebase Hosting to publish static resources like sounds or images used by your Assistant app, or you can use the Firebase Realtime Database to easily store simple data. This can be even more beneficial if you’re using those same services from your other apps on any of the platforms supported by Firebase, allowing you to easily share a serverless architecture.

Create an Assistant project and setup the webhook sample code

Let’s see how you can set up a project starting from our webhook template for API.AI. Start by creating a project in the Actions on Google console. I’ll call mine “My Assistant App”).

After the project is created, click API.AI in the Add actions to your app section, then click the Create Actions on API.AI button: this opens the API.AI console for a new project, click Save to, well, save it :)

Now let’s get our webhook running. First, clone or download our webhook template for API.AI to a folder of your liking. Install the Firebase CLI, then execute firebase init functions from the folder where you downloaded the sample. The Firebase CLI presents you with a choice of Firebase projects, from which you can pick the project created in the Actions on Google console.

After the selection of the project, the CLI creates a functions folder containing an index.js file for your code and a package.json file to declare the dependencies of your project. In our case those files are already present because we are importing an existing sample, so when the CLI asks whether you want to overwrite the files or not reply no! Well, it’s the default choice anyway :). The Firebase CLI also asks whether you want to install your dependencies using npm: let’s reply yes, so that your code will be ready to run!

Deploy and test!

Time to serve our webhook template and configure our app to use it.

For a faster development cycle is better to serve the webhook locally using the “firebase serve” command. The only problem is that Google cannot reach such a webhook because it’s served from your localhost, so we wouldn’t be able to test our actions end to end. One solution is to create a secure tunnel to our localhost and expose it behind an HTTPS endpoint using a program like ngrok. Follow the ngrok instructions to install it, it’s just a matter of downloading it and unzipping it :)

Now let’s serve our webhook template executing firebase serve — only functions. The final line of the output tells us where our webhook is being served. In my case the command output is:

✔ functions: yourAction: http://localhost:5002/my-assistant-app-1d4c2/us-central1/yourAction

The name of the function is yourAction because that is the name of the function that we export in index.js. I’ve highlighted the port (5002) because we need to tell ngrok what port our webhook is listening on. To start the tunnel, cd into the directory where you unzipped ngrok and execute ./ngrok http <port-number>. In my case the complete command is ./ngrok http 5002. While running, ngrok shows this status window (yours will contain different values):

To form the URL of the webhook we need to combine the forwarding HTTPS URL from ngrok (in my case https://123b8189.ngrok.io) with the path of the webhook served by the Firebase CLI (in my case /my-assistant-app-1d4c2/us-central1/yourAction ). The final value for me is https://123b8189.ngrok.io/my-assistant-app-1d4c2/us-central1/yourAction; compose yours and then go back to the API.AI console. Make sure the project you’ve created for this app is selected and select Fulfillment from the left navigation menu. Enable Webhook, set the value of URL to the HTTPS forwarding URL from ngrok, then click Save.

To easily test our webhook we’re now going to set it up as the fulfillment for the default welcome intent: select Intents from the left navigation menu, select the Default Welcome Intent intent, scroll down to the end of the page and open the Fulfillment section by clicking on it, check Use webhook and then click Save.

We can now test our webhook end to end, let’s see how to use the Actions on Google Simulator to do it. In the API.AI console, select Integrations from the left navigation menu, open the Settings menu for Actions on Google, click Authorize if needed, then click Test. When you see the green box Test now active, click View to open the simulator. Type Talk to my test app in the simulator, and you’ll see our “Hello World!” reply.

If you want to deploy the code to the Google servers, run firebase deploy — only functions, and wait for the CLI to do its job and tell you where your code is published. The URL you obtain after firebase deploy is publicly reachable, and you can use it as is when configuring the fulfillment webhook in the API.AI console with no need for a tunnel.

To check more interesting things that you can do with Actions on Google, check out our samples at https://github.com/actions-on-google, and stay tuned for my next post where I’ll talk about how to debug your Assistant apps.