How to build an Action for Google Assistant

Recently, we shared some simple instructions on how to build an Alexa Skill. And because our Alexa developers are big believers in voice apps and all conversational interfaces, here are step-by-step instructions on how to build a custom Action for the Google Assistant.

Instructions for developing a Google Assistant Action

Step 1: Perform initial setup

To start, follow the Actions SDK Quick Start guide, with some small tweaks to improve the overall setup and get everything ready for the Google Assistant Action development.

• Install Node.js 14, the most recent version of node we can use on Firebase Lambdas.

• Install and set up Firebase CLI by following these instructions.

• Install and set up Gactions CLI. I recommend installing it using npm i -g @assistant/gactions.

• Setup a billing account on Google Cloud APIs. Don’t worry, you will not be charged unless you have many users interacting with your action.

Step 2: Understand Conversational Actions

Before you go any further, you should understand how Conversational Actions work.

Conversational Actions operate by processing a user query, either through voice or text, which is captured by the Google Assistant and interpreted using natural language understanding (NLU). Consider the following phrase:

“Ok Google, talk to Facts about Ferrets.”

NLU allows the Google Assistant platform to identify an intent and its optional slots from a user query. In the example above, the user intent is to know about ferrets by using the custom Google Action called Facts. Within the intent, the slot “Ferrets” is a variable value that allows for dynamic responses to the user. Google routes the intent to your action, and you as a developer handle it and provide a response to the user. You are in control.

Sequence diagram of user interaction with the Google Assistant, including a fulfillment service (source: Google).

Intents usually lead to scenes. A scene is an individual state of the conversation. It organizes your conversation into logical chunks, executes tasks, and returns prompts to users.

Scenes can also be transitioned from other scenes and consist of the following states: On Enter, Conditions, Slot Filling, Prompts, and Input.

• On Enter: A one-time setup for the scene.

• Conditions: The evaluation of certain criteria before triggering other scene behaviors.

• Slot filling: The scene can automatically collect required slots in this stage.

• Prompts: The prompt queue delivery.

• Input: An intent matching, continuation of slot filling (if it isn’t complete), or no match or no input errors handling.

When a scene is done executing, it typically sends a prompt back to users to continue the conversation. Or it can end the conversation if appropriate. You as a developer can choose what’s best.

In addition, your Actions can delegate extra work to a fulfillment service, which is a web service built by you that communicates with your Action via webhooks. This lets you validate data, call other web services, carry out business logic, and more.

This Interactive Canvas sample contains a Game scene, which is responsible for triggering a webhook handler for each intent it receives.

A Google Action scene named Game, showing that the Change Color intent handler is calling a webhook tied to your fulfillment service.

Step 3: Create a new project for your Google Action

Once you have a good understanding of Conversational Actions, it’s time to create a new project.

First, go to the Actions console.

Click New project, enter a project name and click Create project.

Select a category and click Next.

Select Blank project and click Start building.

Enable the Actions API, Cloud Functions API, and Cloud Build API in the Google Cloud console by following the instructions in Enable and disable APIs.

Your project is created. Now set up your local environment for development.

Using your Terminal, navigate to a folder where you would like to host your code and initialize a new project using the Interactive Canvas template by executing this command:

gactions init interactive-canvas --dest interactive-canvas-sample
cd interactive-canvas-sample

The Interactive Canvas sample project includes the Interactive Canvas framework. This framework allows developers to add visual interactions to Conversational Actions with web elements such as HTML, CSS, and Javascript.

This template has good demonstrations of how scenes and intents work.

Now open the interactive-canvas-sample/sdk/settings/settings.yaml file and change the value of the projectId field to your project’s ID.

To get your project’s ID, open your newly created project in the Actions Console and click the more icon at the top-right corner. Then, select Project settings and copy the string in the Project ID field.

A pop-up with an arrow pointing to the highlighted Project Settings options in the top-right corner of the Actions Console.

Whenever you run gactions push inside the interactive-canvas-sample/sdk/ folder, the project in the Actions Console will be updated as well.

You can also pull changes made in the console to the project by running gactions pull.

To learn about other commands and options you can use with gactions CLI, take a look here.

Before proceeding to the next step, take a look at the project files and folder that was started for our action.

You’ll notice that your project’s folder is an npm package with public and sdk folders.

The public folder contains the webview portion of the project and the sdk has the actual Google Action itself, including its intents, scenes, types, settings, and webhook code.

The project’s folder structure after being initialized with the Gactions CLI.

The default setup for a fulfillment service is Inline Cloud Functions. Therefore, the webhook handler’s logic that is located at sdk/webhooks/ActionsOnGoogleFulfillment/index.js is also available in the web editor in the webhook side tab in the console. Take a look at the code there to understand how handlers are created.

To customize it, use the @assistant/conversation library.

The samples page is very useful for learning how to implement features such as account linking, push notifications, localization, and more.

Step 4: Test with preview deployment

After you set up the sample, you can deploy the Interactive Canvas web app and your Actions project. This process creates a draft version of your Actions project that you can deploy to the Actions simulator for previewing and testing.

From the interactive-canvas-sample/ directory, run the following command to deploy the Interactive Canvas web app (the contents of the public/ directory):

firebase deploy --project PROJECT_ID --only hosting

You can see a rendered version of the web app at the URL returned by the Firebase CLI in a browser. It will be something like: https://PROJECT_ID.web.app.

Now, open the interactive-canvas-sample/sdk/webhooks/ActionsOnGoogleFulfillment/index.js file and change the value of the CANVAS_URL variable to your project’s web app URL.

const CANVAS_URL = 'https://PROJECT_ID.web.app';

From the interactive-canvas-sample/sdk/ directory, run gactions push to push the local version of your Actions project to the console as a draft version. Then run gactions deploy preview to create a preview version from the draft so you can test it using the Google Console Simulator.

Step 5: Beta test your Google Action

If you want to make sure your Google Action is delivering the best user experience possible, you might release it first to Alpha and Beta channels.

Go to the Deploy tab and fill in the required information such as Action description, images, contact details, and so on.

In the Release section, you can choose between Alpha, Beta, and Production channels.

Choose Alpha if you want to deploy your custom Google Action to a channel that should be used to quickly test early versions of your final product. The Alpha Channel allows for external testers to be invited through email, up to 20 users, and a review by Google is not required.

The Beta Channel is used when you want to distribute the Action to a wider audience of up to 200 users. To publish your action in this channel, you will need a full Google review. Before you do, make sure to take a look at this checklist. It has a set of best practices regarding the action’s display name, invocation phrase, and user interface. It’s also a good opportunity to validate your current implementation ahead of an official launch date. It reduces the risk of missing a deadline, since you can’t make code changes and instantly deploy to production.

To manage both Alpha and Beta Channel users, click on their buttons in the top-right corner of the Deploy page.

Step 6: Release your Action to production

The process to release the Action to production is similar to releasing it to the Beta channel.

At the Deploy tab, click on the Release section and start a new release for production.

If the Action has already been approved by Google in the Beta channel — and no other changes are required — it will be pushed directly to Production. Otherwise, Google will review your Action and provide feedback through email and the Actions Console. It could take a few days depending on the complexity of your Action.

A new release creation popup with the production option selected.

Once your release is approved to be deployed to production, Google will start the rollout process, which can take a few hours. After that, the Action will be available for any Google Assistant user that has a supported device based on your action capabilities and is within the countries that you have allowed. A user doesn’t have to enable the Action, they just need to say “Ok Google, Talk to ”.For more information about releasing a Google Action refer to Google’s official documentation.

Need more help with your Google Action?

Google’s Action Builder is powerful but can be overwhelming at first. Hopefully, this blog post has given you a general understanding of how Actions work and the instructions to develop your own. If you’re looking for more advanced topics, check out manual and automated testing, deep-link invocations, and localization.

If you need additional help from our experienced voice app engineers — or you want a voice app for your brand or business — contact us and let’s talk!