Constructor

ActionsSdkApp

new ActionsSdkApp(options)

Parameters

Name Description

options

Object

JSON configuration.

Example

const ActionsSdkApp = require('actions-on-google').ActionsSdkApp;
const app = new ActionsSdkApp({request: request, response: response,
  sessionStarted:sessionStarted});

Methods

ask

ask(inputPrompt, dialogState)

Asks to collect user's input; all user's queries need to be sent to the app.

Parameters

Name Description

inputPrompt

(Object, SimpleResponse, or RichResponse)

Holding initial and no-input prompts.

dialogState

Optional

Object

JSON object the app uses to hold dialog state that will be circulated back by App.

Returns

The response that is sent to Assistant to ask user to provide input.

Example

const app = new ActionsSdkApp({request: request, response: response});

function mainIntent (app) {
  const inputPrompt = app.buildInputPrompt(true, '<speak>Hi! <break time="1"/> ' +
        'I can read out an ordinal like ' +
        '<say-as interpret-as="ordinal">123</say-as>. Say a number.</speak>',
        ['I didn\'t hear a number', 'If you\'re still there, what\'s the number?', 'What is the number?']);
  app.ask(inputPrompt);
}

function rawInput (app) {
  if (app.getRawInput() === 'bye') {
    app.tell('Goodbye!');
  } else {
    const inputPrompt = app.buildInputPrompt(true, '<speak>You said, <say-as interpret-as="ordinal">' +
      app.getRawInput() + '</say-as></speak>',
        ['I didn\'t hear a number', 'If you\'re still there, what\'s the number?', 'What is the number?']);
    app.ask(inputPrompt);
  }
}

const actionMap = new Map();
actionMap.set(app.StandardIntents.MAIN, mainIntent);
actionMap.set(app.StandardIntents.TEXT, rawInput);

app.handleRequest(actionMap);

askForDeliveryAddress

askForDeliveryAddress(reason, dialogState) returns Object

Asks user for delivery address.

Parameters

Name Description

reason

string

Reason given to user for asking delivery address.

dialogState

Optional

Object

JSON object the app uses to hold dialog state that will be circulated back by Assistant.

Returns

Object HTTP response.

Example

const app = new ActionsSdkApp({request, response});
const WELCOME_INTENT = app.StandardIntents.MAIN;
const DELIVERY_INTENT = app.StandardIntents.DELIVERY_ADDRESS;

function welcomeIntent (app) {
  app.askForDeliveryAddress('To make sure I can deliver to you');
}

function addressIntent (app) {
  const postalCode = app.getDeliveryAddress().postalAddress.postalCode;
  if (isInDeliveryZone(postalCode)) {
    app.tell('Great looks like you\'re in our delivery area!');
  } else {
    app.tell('I\'m sorry it looks like we can\'t deliver to you.');
  }
}

const actionMap = new Map();
actionMap.set(WELCOME_INTENT, welcomeIntent);
actionMap.set(DELIVERY_INTENT, addressIntent);
app.handleRequest(actionMap);

askWithCarousel

askWithCarousel(inputPrompt, carousel, dialogState)

Asks to collect user's input with a carousel.

Parameters

Name Description

inputPrompt

(Object, SimpleResponse, or RichResponse)

Holding initial and no-input prompts. Cannot contain basic card.

carousel

Carousel

Carousel built with buildCarousel.

dialogState

Optional

Object

JSON object the app uses to hold dialog state that will be circulated back by Assistant.

Returns

The response that is sent to Assistant to ask user to provide input.

Example

const app = new ActionsSdkApp({request, response});

function welcomeIntent (app) {
  app.askWithCarousel('Which of these looks good?',
    app.buildCarousel()
     .addItems([
       app.buildOptionItem(SELECTION_KEY_ONE,
         ['synonym of KEY_ONE 1', 'synonym of KEY_ONE 2'])
         .setTitle('Number one'),
       app.buildOptionItem(SELECTION_KEY_TWO,
         ['synonym of KEY_TWO 1', 'synonym of KEY_TWO 2'])
         .setTitle('Number two'),
     ]));
}

function optionIntent (app) {
  if (app.getSelectedOption() === SELECTION_KEY_ONE) {
    app.tell('Number one is a great choice!');
  } else {
    app.tell('Number two is a great choice!');
  }
}

const actionMap = new Map();
actionMap.set(app.StandardIntents.TEXT, welcomeIntent);
actionMap.set(app.StandardIntents.OPTION, optionIntent);
app.handleRequest(actionMap);

askWithList

askWithList(inputPrompt, list, dialogState)

Asks to collect user's input with a list.

Parameters

Name Description

inputPrompt

(Object, SimpleResponse, or RichResponse)

Holding initial and no-input prompts. Cannot contain basic card.

list

List

List built with buildList.

dialogState

Optional

Object

JSON object the app uses to hold dialog state that will be circulated back by Assistant.

Returns

The response that is sent to Assistant to ask user to provide input.

Example

const app = new ActionsSdkApp({request, response});

function welcomeIntent (app) {
  app.askWithlist('Which of these looks good?',
    app.buildList('List title')
     .addItems([
       app.buildOptionItem(SELECTION_KEY_ONE,
         ['synonym of KEY_ONE 1', 'synonym of KEY_ONE 2'])
         .setTitle('Number one'),
       app.buildOptionItem(SELECTION_KEY_TWO,
         ['synonym of KEY_TWO 1', 'synonym of KEY_TWO 2'])
         .setTitle('Number two'),
     ]));
}

function optionIntent (app) {
  if (app.getSelectedOption() === SELECTION_KEY_ONE) {
    app.tell('Number one is a great choice!');
  } else {
    app.tell('Number two is a great choice!');
  }
}

const actionMap = new Map();
actionMap.set(app.StandardIntents.TEXT, welcomeIntent);
actionMap.set(app.StandardIntents.OPTION, optionIntent);
app.handleRequest(actionMap);

buildInputPrompt

buildInputPrompt(isSsml, initialPrompt, noInputs) returns Object

Builds the InputPrompt object from initial prompt and no-input prompts.

The App needs one initial prompt to start the conversation. If there is no user response, the App re-opens the mic and renders the no-input prompts three times (one for each no-input prompt that was configured) to help the user provide the right response.

Note: we highly recommend app to provide all the prompts required here in order to ensure a good user experience.

Parameters

Name Description

isSsml

boolean

Indicates whether the text to speech is SSML or not.

initialPrompt

string

The initial prompt the App asks the user.

noInputs

Optional

Array of string

Array of re-prompts when the user does not respond (max 3).

Returns

Object An InputPrompt object.

Example

const inputPrompt = app.buildInputPrompt(false, 'Welcome to action snippets! Say a number.',
    ['Say any number', 'Pick a number', 'What is the number?']);
app.ask(inputPrompt);

getActionVersionLabel

getActionVersionLabel() returns string

Gets the "versionLabel" specified inside the Action Package. Used by app to do version control.

Returns

string The specified version label or null if unspecified.

Example

const app = new ActionsSdkApp({request: request, response: response});
const actionVersionLabel = app.getActionVersionLabel();

getArgument

getArgument(argName) returns string

Get the argument value by name from the current intent. If the argument is not a text argument, the entire argument object is returned.

Note: If incoming request is using an API version under 2 (e.g. 'v1'), the argument object will be in Proto2 format (snake_case, etc).

Parameter

Name Description

argName

string

Name of the argument.

Returns

string Argument value matching argName or null if no matching argument.

getConversationId

getConversationId() returns string

Gets the unique conversation ID. It's a new ID for the initial query, and stays the same until the end of the conversation.

Returns

string Conversation ID or null if no value.

Example

const app = new ActionsSdkApp({request: request, response: response});
const conversationId = app.getConversationId();

getDateTime

getDateTime() returns DateTime

Gets user provided date and time. Use after askForDateTime.

Returns

DateTime Date and time given by the user. Null if no user date and time given.

getDeliveryAddress

getDeliveryAddress() returns DeliveryAddress

Gets order delivery address. Only use after calling askForDeliveryAddress.

Returns

DeliveryAddress Delivery address information. Null if user denies permission, or no address given.

getDeviceLocation

getDeviceLocation() returns DeviceLocation

If granted permission to device's location in previous intent, returns device's location (see askForPermissoins). If device info is unavailable, returns null.

Returns

DeviceLocation Null if location permission is not granted.

Example

const app = new ActionsSdkApp({request: req, response: res});
app.askForPermission("To get you a ride",
  app.SupportedPermissions.DEVICE_PRECISE_LOCATION);
// ...
// In response handler for subsequent intent:
if (app.isPermissionGranted()) {
  sendCarTo(app.getDeviceLocation().coordinates);
}

getDialogState

getDialogState() returns Object

Gets previous JSON dialog state that the app sent to Assistant. Alternatively, use the app.data field to store JSON values between requests.

Returns

Object JSON object provided to the Assistant in the previous user turn or {} if no value.

Example

const app = new ActionsSdkApp({request: request, response: response});
const dialogState = app.getDialogState();

getInputType

getInputType() returns number

Gets type of input used for this request.

Returns

number One of ActionsSdkApp.InputTypes. Null if no input type given.

getIntent

getIntent() returns string

Get the current intent. Alternatively, using a handler Map with handleRequest, the client library will automatically handle the incoming intents.

Returns

string Intent id or null if no value.

Example

const app = new ActionsSdkApp({request: request, response: response});

function responseHandler (app) {
  const intent = app.getIntent();
  switch (intent) {
    case app.StandardIntents.MAIN:
      const inputPrompt = app.buildInputPrompt(false, 'Welcome to action snippets! Say anything.');
      app.ask(inputPrompt);
      break;

    case app.StandardIntents.TEXT:
      app.tell('You said ' + app.getRawInput());
      break;
  }
}

app.handleRequest(responseHandler);

getRawInput

getRawInput() returns string

Gets the user's raw input query.

Returns

string User's raw query or null if no value.

Example

const app = new ActionsSdkApp({request: request, response: response});
app.tell('You said ' + app.getRawInput());

getSelectedOption

getSelectedOption() returns string

Returns the option key user chose from options response.

Returns

string Option key of selected item. Null if no option selected or if current intent is not OPTION intent.

Example

const app = new App({request: req, response: res});

function pickOption (app) {
  if (app.hasSurfaceCapability(app.SurfaceCapabilities.SCREEN_OUTPUT)) {
    app.askWithCarousel('Which of these looks good?',
      app.buildCarousel().addItems(
        app.buildOptionItem('another_choice', ['Another choice']).
        setTitle('Another choice').setDescription('Choose me!')));
  } else {
    app.ask('What would you like?');
  }
}

function optionPicked (app) {
  app.ask('You picked ' + app.getSelectedOption());
}

const actionMap = new Map();
actionMap.set(app.StandardIntents.TEXT, pickOption);
actionMap.set(app.StandardIntents.OPTION, optionPicked);

app.handleRequest(actionMap);

getSignInStatus

getSignInStatus() returns string

Gets status of user sign in request.

Returns

string Result of user sign in request. One of ActionsSdkApp.SignInStatus. Null if no sign in status.

getSurfaceCapabilities

getSurfaceCapabilities() returns Array of string

Gets surface capabilities of user device.

Returns

Array of string Supported surface capabilities, as defined in ActionsSdkApp.SurfaceCapabilities.

getTransactionDecision

getTransactionDecision() returns TransactionDecision

Gets transaction decision information. Only use after calling askForTransactionDecision.

Returns

TransactionDecision Transaction decision data. Returns object with userDecision. userDecision will be one of Transactions.ConfirmationDecision. Null if no decision given.

getTransactionRequirementsResult

getTransactionRequirementsResult() returns string

Gets transactability of user. Only use after calling askForTransactionRequirements. Null if no result given.

Returns

string One of Transactions.ResultType.

getUser

getUser() returns User

Gets the User object. The user object contains information about the user, including a string identifier and personal information (requires requesting permissions, see askForPermissions).

Returns

User Null if no value.

Example

const app = new ActionsSdkApp({request: request, response: response});
const userId = app.getUser().userId;

getUserConfirmation

getUserConfirmation() returns boolean

Gets confirmation decision. Use after askForConfirmation.

Returns

boolean True if the user replied with affirmative response. False if user replied with negative response. Null if no user confirmation decision given.

isInSandbox

isInSandbox() returns boolean

Returns true if the app is being tested in sandbox mode. Enable sandbox mode in the (Actions console)[console.actions.google.com] to test transactions.

Returns

boolean True if app is being used in Sandbox mode.

isPermissionGranted

isPermissionGranted() returns boolean

Returns true if the request follows a previous request asking for permission from the user and the user granted the permission(s). Otherwise, false. Use with askForPermissions.

Returns

boolean true if permissions granted.

Example

const app = new ActionsSdkApp({request: request, response: response});
app.askForPermissions("To get you a ride", [
  app.SupportedPermissions.NAME,
  app.SupportedPermissions.DEVICE_PRECISE_LOCATION
]);
// ...
// In response handler for subsequent intent:
if (app.isPermissionGranted()) {
 // Use the requested permission(s) to get the user a ride
}

tell

tell(textToSpeech)

Tells Assistant to render the speech response and close the mic.

Parameter

Name Description

textToSpeech

(string, SimpleResponse, or RichResponse)

Final response. Spoken response can be SSML.

Returns

The HTTP response that is sent back to Assistant.

Example

const app = new ActionsSdkApp({request: request, response: response});

function mainIntent (app) {
  const inputPrompt = app.buildInputPrompt(true, '<speak>Hi! <break time="1"/> ' +
        'I can read out an ordinal like ' +
        '<say-as interpret-as="ordinal">123</say-as>. Say a number.</speak>',
        ['I didn\'t hear a number', 'If you\'re still there, what\'s the number?', 'What is the number?']);
  app.ask(inputPrompt);
}

function rawInput (app) {
  if (app.getRawInput() === 'bye') {
    app.tell('Goodbye!');
  } else {
    const inputPrompt = app.buildInputPrompt(true, '<speak>You said, <say-as interpret-as="ordinal">' +
      app.getRawInput() + '</say-as></speak>',
        ['I didn\'t hear a number', 'If you\'re still there, what\'s the number?', 'What is the number?']);
    app.ask(inputPrompt);
  }
}

const actionMap = new Map();
actionMap.set(app.StandardIntents.MAIN, mainIntent);
actionMap.set(app.StandardIntents.TEXT, rawInput);

app.handleRequest(actionMap);