Build fulfillment

Fulfillment defines the conversational interface for your Actions project 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 you can build fulfillment using the Actions SDK with the Node.js or the Java/Kotlin client library:

  1. Initialize the ActionsSdkApp object.
  2. Create functions to handle requests in your fulfillment logic.

Building dialogs

Initialize the ActionsSdkApp object

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

Actions SDK (Node.js)
'use strict';

const {actionssdk} = require('actions-on-google');
const functions = require('firebase-functions');

const app = actionssdk({debug: true});

app.intent('actions.intent.MAIN', (conv) => {
  conv.ask('Hi!');
});

// More intent handling if needed
exports.myFunction = functions.https.onRequest(app);
Actions SDK (Java)
ResponseBuilder responseBuilder = getResponseBuilder(request).add("Hi!");
return responseBuilder.build();
JSON
{
  "expectUserResponse": true,
  "expectedInputs": [
    {
      "inputPrompt": {
        "richInitialPrompt": {
          "items": [
            {
              "simpleResponse": {
                "textToSpeech": "Hi!"
              }
            }
          ]
        }
      },
      "possibleIntents": [
        {
          "intent": "actions.intent.TEXT"
        }
      ]
    }
  ],
  "conversationToken": "{\"data\":{}}",
  "userStorage": "{\"data\":{}}"
}

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.

  2. Call the conv.ask() function passing the response you want to show as an argument.

The following code shows how to build a simple response:

Actions SDK (Node.js)
conv.ask(`Hi! Say something, and I'll repeat it.`);
Actions SDK (Java)
ResponseBuilder responseBuilder =
    getResponseBuilder(request).add("Hi! Say something, and I'll repeat it.");
return responseBuilder.build();
JSON
{
  "expectUserResponse": true,
  "expectedInputs": [
    {
      "inputPrompt": {
        "richInitialPrompt": {
          "items": [
            {
              "simpleResponse": {
                "textToSpeech": "Hi! Say something, and I'll repeat it."
              }
            }
          ]
        }
      },
      "possibleIntents": [
        {
          "intent": "actions.intent.TEXT"
        }
      ]
    }
  ],
  "conversationToken": "{\"data\":{}}",
  "userStorage": "{\"data\":{}}"
}

Handling intents

Once you have all your functions to handle triggered intents, use app.intent to assign handlers to intents.

Actions SDK (Node.js)
app.intent('actions.intent.TEXT', (conv) => {
  // handle text intent.
});
app.intent('actions.intent.MAIN', (conv) => {
  // handle main intent.
});
Actions SDK (Java)
@ForIntent("actions.intent.MAIN")
public ActionResponse main(ActionRequest request) {
  // handle main intent
  // ...
}

@ForIntent("actions.intent.TEXT")
public ActionResponse text(ActionRequest request) {
  // handle text intent
  // ...
}

Ending conversations

When you no longer want any user input in return and want to end the conversation, call the conv.close() function. This function tells the Google Assistant to speak back the text to the user and end the conversation by closing the microphone.

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. Call the conv.ask() function passing your response as an argument. The Google Assistant speaks your response to the user 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:

Actions SDK (Node.js)
// handle the initialTrigger
function handleMainIntent(conv, input) {
  conv.ask(input);
}
Actions SDK (Java)
private ActionResponse handleMainIntent(ResponseBuilder rb, String input) {
  return rb.add(input).build();
}

Conversation state

If you are using the conversation HTTP/JSON webhook API, you can maintain the state of your conversations with a JSON formatted object (conversationToken) that is passed back and forth between you and the Google Assistant. If you are using the Node.js client library, you can write to and read from the conv.data field directly. This field is passed back and forth automatically between requests and responses.

Actions SDK (Node.js)
conv.data = {something: 10};
let value = conv.data.something;
Actions SDK (Java)
ResponseBuilder rb = getResponseBuilder(request);
rb.getConversationData().put("something", 10);
Object value = rb.getConversationData().get("something");