Join the Actions on Google Developer Challenge to win a trip to Google I/O 2018 and more than 20 other prizes.

Build Fulfillment

Fulfillment defines the conversational interface for your app to obtain user input and the logic to process the input and eventually fulfill the action.

Overview

Your fulfillment receives requests from the Assistant, processes the request and responds. This back-and-forth request and response process drives the conversation forward until you eventually fulfill the initial user request.

The following steps describe how to build fulfillment with the Node.js client library:

  1. Initialize the ActionsSdkApp object.
  2. Create functions to handle requests in your fulfillment logic.
  3. Build and initialize an action map that maps intents to functions. When your endpoint receives a request, the client library checks the intent associated with the request and automatically calls the appropriate function.

Building dialogs

Initialize the ActionsSdkApp object

The following code instantiates ActionsSdkApp and does some boilerplate Node.js setup for Google Cloud Functions:

'use strict';

const ActionsSdkApp = require('actions-on-google').ActionsSdkApp;

exports.<insertCloudFunctionName>= (req, res) => {
  const app = new ActionsSdkApp({request: req, response: res});

  // Create functions to handle requests here

}

Create functions to handle requests

When users speak a phrase, you receive a request from the Google Assistant. To fulfill the intents that come in requests, create functions that handle the triggered intent.

To handle requests:

  1. Carry out any logic required to process the user input. You'll typically call the following get functions to get user input from the request.

  2. Build an input prompt with buildInputPrompt() to create the text to speak back to users.

  3. Call the ask() function with the input prompt.

The following code shows how to build a simple response:

function mainIntent (app) {
  let inputPrompt = app.buildInputPrompt(false,
    'Hi! Say something, and I\'ll repeat it');
  app.ask(inputPrompt);
}

function respond (app) {
  let inputPrompt = app.buildInputPrompt(false,
    'Hi! Say something, and I\'ll repeat it.');
  app.ask(inputPrompt);
}

Build and initialize an action map

Once you have all your functions to handle triggered intents, build an action map to map intents to functions.

let actionMap = new Map();
actionMap.set(app.StandardIntents.MAIN, mainIntent);
actionMap.set(app.StandardIntents.TEXT, respond);

//add more intents to the map
...

app.handleRequest(actionMap);

If you have only one handler function, then you don't need to do this and just pass in the function name to handleRequest. In this case, all triggered intents will call this function, so you have to check for the intent that is triggered to do the appropriate thing.

function responseHandler (app) {
  // intent contains the name of the intent you defined in `initialTriggers`
  let intent = app.getIntent();
  switch (intent) {
    case app.StandardIntents.MAIN:
      app.ask('Welcome! Say a number.');
      break;

    case app.StandardIntents.TEXT:
      let number = app.getArgument(NUMBER_ARGUMENT);
      app.tell('You said ' + number);
      break;
  }
}
// you can add the function name instead of an action map
app.handleRequest(responseHandler);

Ending conversations

When you no longer want any user input in return and want to end the conversation, call the tell() function. This function tells the Google Assistant to speak back the text to the user and end the conversation by closing the microphone. You need to call this function at least once in your Conversation Action.

Handling the main invocation intent

When users trigger the app.intent.action.MAIN intent, you normally don't need to do any user input processing. If your action package contains many actions and covers many use cases, it's a good idea to orient the user by telling them a few things that they can do.

  1. Build an input prompt with 'buildInputPrompt()' that orients the user and describes a few things your actions can do.
  2. Call the ask() function with the input prompt. The Google Assistant speaks the input prompt to the user as a response and then waits for the user to trigger one of the intents that you specified.

The following snippet shows how to handle a simple welcome intent:

// handle the initialTrigger
function mainIntent (app) {
  let inputPrompt = app.buildInputPrompt(false, 'Hi, I\'m Do It All. You can ask to do this or that. What would you like to do?');
  app.ask(inputPrompt);
}

Conversation state

You can maintain state of your conversations with a JSON formatted object that is passed back and forth between you and the Google Assistant.

You can write to and read from the app.data field directly. This field is passed back and forth automatically when handleRequest() is called and your endpoint is ready to receive requests.

app.data = { something:10 }
... 
let value = app.data.something

Or, you can use the ask() function to pass the dialog state to the Google Assistant as a JSON object and then read it with getDialogState() when you receive a response.

// get state object and modify it
let state = app.getDialogState();
...
// return it in the response
app.ask(inputPrompt, state);