Client Library for Building Webhooks

To more easily build webhooks for fulfuillment, we provide a client library to facilitate communication between your webhook endpoint and API.AI /Google Assistant.

The client library implements an Assistant class that is instantiated with the HTTP request and response parameters:

const assistant = new Assistant({request: request, response: response});

The following methods are supported:

Method Description
Assistant(options) Constructor for the Assistant class. Options is a JSON object with the following fields:
  • request - HTTP request object
  • response - HTTP response object
ask(text) Provide the String SSML text for the user prompt and expect a response.
tell(text) Provide the String SSML text for the user prompt without expecting a response.
getArgument(argument) Get the value of the intent parameter by String name.
handleRequest(map) Intent handler that is specified with a Map of a function for each intent name. Each function should return a Promise.
setContext(context, lifespan, parameters) Set the intent context to the new String value. Optional parameters for Integer lifespan and JSON parameters.
getUser Get the user object from Google.
getCapabilities Get the device capabilities object.

The following fields are supported by the Assistant instance:

Name Description
data JSON data that is accessible during a conversational session.
state A String state name that is used by the client library for state-based mapping logic.

Using SSML

The following code snippet shows you how to use SSML:

function saySSML(assistant) {
    return new Promise(function(resolve, reject) {
      let text_to_speech = 'Here are <say-as interpet-as="characters">SSML</say-as> samples. '
        + 'I can pause <break time="3"/>. '
        + 'I can play a sound <audio src="https://www.example.com/MY_WAVE_FILE.wav">your wave file</audio>. '
        + 'I can speak in cardinals. Your position is <say-as interpret-as="cardinal">10</say-as> in line. '
        + 'Or I can speak in ordinals. You are <say-as interpret-as="ordinal">10</say-as> in line. '
        + 'Or I can even speak in digits. Your position in line is <say-as interpret-as="digits">10</say-as>. '
        + 'I can also substitute phrases, like the <sub alias="World Wide Web Consortium">W3C</sub>. '
        + 'Finally, I can speak a paragraph with two sentences. '
        + '<p><s>This is sentence one.</s><s>This is sentence two.</s></p>'
      resolve(assistant.tell(text_to_speech));
    });
  };

See the SSML reference documentation for more information.

Sample Usage

The following sample uses the Node.js "express" module to create a web server and then uses the Actions On Google client library to implement a random number game.

'use strict';

process.env.DEBUG = 'actions-on-google:*';
let Assistant = require("./actions-on-google");
let express = require('express');
let bodyParser = require('body-parser');

let app = express();
app.set('port', (process.env.PORT || 8080));
app.use(bodyParser.json({type: 'application/json'}));

function getRandomNumber(min, max) {
  return Math.floor(Math.random() * (max - min + 1)) + min;
}

const GENERATE_ANSWER_ACTION = 'generate_answer';
const CHECK_GUESS_ACTION = 'check_guess';

app.post('/', function (request, response) {
  const assistant = new Assistant({request: request, response: response});

  function generateAnswer(assistant) {
    return new Promise(function (resolve, reject) {
      var answer = getRandomNumber(1, 100);
      assistant.data.answer = answer;
      resolve(assistant.ask('I\'m thinking of a number from 0 and 100. What\'s your first guess?'));
    });
  }

  function checkGuess(assistant) {
    return new Promise(function (resolve, reject) {
      let answer = assistant.data.answer;
      let guess = parseInt(assistant.getArgument('guess'));
      if (answer > guess) {
        resolve(assistant.ask('It\'s higher than ' + guess + '. What\'s your next guess?'));
      } else if (answer < guess) {
        resolve(assistant.ask('It\'s lower than ' + guess + '. Next guess?'));
      } else {
        resolve(assistant.tell('Congratulations, that\'s it! I was thinking of ' + answer));
      }
    });
  }

  let actionMap = new Map();
  actionMap.set(GENERATE_ANSWER_ACTION, generateAnswer);
  actionMap.set(CHECK_GUESS_ACTION, checkGuess);

  assistant.handleRequest(actionMap);
});

// Start the server
var server = app.listen(app.get('port'), function () {
  console.log('App listening on port %s', server.address().port);
  console.log('Press Ctrl+C to quit.');
});