Getting Started with the Actions SDK

This document guides you through deploying a simple Conversation Action that uses SSML. The action asks you to say a number and it speaks it back to you as an ordinal (for example, if you say "1", the action says "first").

Setup your environment

This tutorial assumes you're using Google Cloud Functions, but you can use any web hosting platform to deploy your Conversation Action fulfillment logic.

  1. Download and install Node.js
  2. Download, install, and initialize the Google Cloud SDK.
  3. Download gactions and save it to a directory we'll refer to as <sdk-dir>
  4. Go to the Google Cloud Console projects page. Select a project if you already have one you want to use or create a new project to host your fulfillment logic. Make a note of the project ID, because it is used for configuration and deployment.
  5. Enable billing for your project. See the console's help center for more information.
  6. Create a Storage Bucket for your Google Developer Project. Make a note of the storage bucket name.

Get the sample and client library

To get the the sample and client library, run the following commands:

git clone https://github.com/actions-on-google/actionssdk-say-number-nodejs.git
cd actionssdk-say-number-nodejs
npm install

Deploy fulfillment and preview the action package

Previewing the action package lets you make it available in a staging area that's only available to the account that is logged in to the gactions tool. To do this, you need to deploy fulfillment to a web server and then preview the action package with the gactions CLI.

  1. Deploy the Node.js Cloud Function for fulfillment with the following commands:

    cd actionssdk-say-number-nodejs
    gcloud beta functions deploy sayNumber --trigger-http --stage-bucket <storage_bucket_name>
    

    You can read server logs with

    gcloud beta functions logs read
    
  2. Modify the action.json file in the following places:

    • agentInfo.projectId - Specify your Google developer project ID
    • httpExecution.url - Specify fulfillment URL of the deployed Node.js Cloud Function from step 1
  3. Run the following commands from the actionssdk-say-number-nodejs directory:

    <sdk-dir>/gactions preview -action_package=action.json -invocation_name="my action"
    

    You should receive a message to authorize gactions to access your account and Google developer project. Follow the onscreen instructions to do so.

  4. Preview the action package by running the following command:

    <sdk-dir>/gactions simulate
    
  5. Enter talk to my action to invoke the action.

Sample Explanation

The following directory structure describes the important files for this sample:

<sdk-dir>
|- gactions
|- <sample-dir>
   |- actions-on-google.js - Node.js client library
   |- action.json - The action package that defines your actions
   |- index.js - The fulfillment logic for Google Cloud Functions
   |- package.json - Node.js metadata

The two most important files are index.js and action.json, the two main parts of this Conversation Action.

  • action.json - This action package defines one action with an initialTrigger that declares a "assistant.intent.action.MAIN" intent (required for every action package). This intent is triggered when you say "talk to my action".

    When the main intent is triggered, the Google Assistant hands off the user experience to the Conversation Action, and the action welcomes the user.

  • index.js - There are two main functions in the fulfillment logic. mainIntent() handles the StandardIntents.MAIN intent being triggered and welcomes the user. The other function, rawInput(), processes the StandardIntents.TEXT intent. If a user says a number, the action speaks it back as an ordinal (for example, if a user says "one", the action speaks back "first"). If the user says "bye", the action quits.