Constructor

AssistantApp

new AssistantApp(options)

Parameters

Name Description

options

Object

JSON configuration.

Enumerations

BuiltInArgNames

read-only

string

List of built-in argument names.

Properties

Name Description

PERMISSION_GRANTED

Permission granted argument.

OPTION

Option selected argument.

TRANSACTION_REQ_CHECK_RESULT

Transaction requirements check result argument.

DELIVERY_ADDRESS_VALUE

Delivery address value argument.

TRANSACTION_DECISION_VALUE

Transactions decision argument.

CONFIRMATION

Confirmation argument.

DATETIME

DateTime argument.

SIGN_IN

Sign in status argument.

ConversationStages

read-only

number

List of possible conversation stages, as defined in the Conversation object.

Properties

Name Description

UNSPECIFIED

Unspecified conversation state.

NEW

A new conversation.

ACTIVE

An active (ongoing) conversation.

InputTypes

read-only

number

List of possible user input types.

Properties

Name Description

UNSPECIFIED

Unspecified.

TOUCH

Input given by touch.

VOICE

Input given by voice (spoken).

KEYBOARD

Input given by keyboard (typed).

InputValueDataTypes_

read-only

string

List of built-in value type names.

Properties

Name Description

PERMISSION

Permission Value Spec.

OPTION

Option Value Spec.

TRANSACTION_REQ_CHECK

Transaction Requirements Check Value Spec.

DELIVERY_ADDRESS

Delivery Address Value Spec.

TRANSACTION_DECISION

Transaction Decision Value Spec.

CONFIRMATION

Confirmation Value Spec.

DATETIME

DateTime Value Spec.

SignInStatus

read-only

string

List of possible sign in result status values.

Properties

Name Description

UNSPECIFIED

OK

CANCELLED

ERROR

StandardIntents

read-only

string

List of standard intents that the app provides.

Properties

Name Description

MAIN

App fires MAIN intent for queries like [talk to $app].

TEXT

App fires TEXT intent when action issues ask intent.

PERMISSION

App fires PERMISSION intent when action invokes askForPermission.

OPTION

App fires OPTION intent when user chooses from options provided.

TRANSACTION_REQUIREMENTS_CHECK

App fires TRANSACTION_REQUIREMENTS_CHECK intent when action sets up transaction.

DELIVERY_ADDRESS

App fires DELIVERY_ADDRESS intent when action asks for delivery address.

TRANSACTION_DECISION

App fires TRANSACTION_DECISION intent when action asks for transaction decision.

CONFIRMATION

App fires CONFIRMATION intent when requesting affirmation from user.

DATETIME

App fires DATETIME intent when requesting date/time from user.

SIGN_IN

App fires SIGN_IN intent when requesting sign-in from user.

SupportedPermissions

read-only

string

List of supported permissions the app supports.

Properties

Name Description

NAME

The user's name as defined in the UserProfile object

DEVICE_PRECISE_LOCATION

The location of the user's current device, as defined in the Location object.

DEVICE_COARSE_LOCATION

City and zipcode corresponding to the location of the user's current device, as defined in the Location object.

SurfaceCapabilities

read-only

string

List of surface capabilities supported by the app.

Properties

Name Description

AUDIO_OUTPUT

The ability to output audio.

SCREEN_OUTPUT

The ability to output on a screen

Methods

askForConfirmation

askForConfirmation(prompt, dialogState)

Asks user for a confirmation.

Parameters

Name Description

prompt

Optional

string

The confirmation prompt presented to the user to query for an affirmative or negative response. If undefined or null, Google will use a generic yes/no prompt.

dialogState

Optional

Object

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

Example

const app = new ApiAiApp({ request, response });
const WELCOME_INTENT = 'input.welcome';
const CONFIRMATION = 'confirmation';

function welcomeIntent (app) {
  app.askForConfirmation('Are you sure you want to do that?');
}

function confirmation (app) {
  if (app.getUserConfirmation()) {
    app.tell('Great! I\'m glad you want to do it!');
  } else {
    app.tell('That\'s okay. Let\'s not do it now.');
  }
}

const actionMap = new Map();
actionMap.set(WELCOME_INTENT, welcomeIntent);
actionMap.set(CONFIRMATION, confirmation);
app.handleRequest(actionMap);

askForDateTime

askForDateTime(initialPrompt, datePrompt, timePrompt, dialogState)

Asks user for a timezone-agnostic date and time.

Parameters

Name Description

initialPrompt

Optional

string

The initial prompt used to ask for a date and time. If undefined or null, Google will use a generic prompt.

datePrompt

Optional

string

The prompt used to specifically ask for the date if not provided by user. If undefined or null, Google will use a generic prompt.

timePrompt

Optional

string

The prompt used to specifically ask for the time if not provided by user. If undefined or null, Google will use a generic prompt.

dialogState

Optional

Object

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

Example

const app = new ApiAiApp({ request, response });
const WELCOME_INTENT = 'input.welcome';
const DATETIME = 'datetime';

function welcomeIntent (app) {
  app.askForDateTime('When do you want to come in?',
    'Which date works best for you?',
    'What time of day works best for you?');
}

function datetime (app) {
  app.tell({speech: 'Great see you at your appointment!',
    displayText: 'Great, we will see you on '
    + app.getDateTime().date.month
    + '/' + app.getDateTime().date.day
    + ' at ' + app.getDateTime().time.hours
    + (app.getDateTime().time.minutes || '')});
}

const actionMap = new Map();
actionMap.set(WELCOME_INTENT, welcomeIntent);
actionMap.set(DATETIME, datetime);
app.handleRequest(actionMap);

askForPermission

askForPermission(context, permission, dialogState)

Asks the Assistant to guide the user to grant a permission. For example, if you want your app to get access to the user's name, you would invoke the askForPermission method with a context containing the reason for the request, and the AssistantApp.SupportedPermissions.NAME permission. With this, the Assistant will ask the user, in your agent's voice, the following: '[Context with reason for the request], I'll just need to get your name from Google, is that OK?'.

Once the user accepts or denies the request, the Assistant will fire another intent: assistant.intent.action.PERMISSION with a boolean argument: AssistantApp.BuiltInArgNames.PERMISSION_GRANTED and, if granted, the information that you requested.

Read more:

Parameters

Name Description

context

string

Context why permission is asked; it's the TTS prompt prefix (action phrase) we ask the user.

permission

string

One of the permissions Assistant supports, each of which comes from AssistantApp.SupportedPermissions.

dialogState

Optional

Object

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

Returns

A response is sent to the Assistant to ask for the user's permission; for any invalid input, we return null.

Example

const app = new ApiAiApp({request: req, response: res});
const REQUEST_PERMISSION_ACTION = 'request_permission';
const GET_RIDE_ACTION = 'get_ride';

function requestPermission (app) {
  const permission = app.SupportedPermissions.NAME;
  app.askForPermission('To pick you up', permission);
}

function sendRide (app) {
  if (app.isPermissionGranted()) {
    const displayName = app.getUserName().displayName;
    app.tell('I will tell your driver to pick up ' + displayName);
  } else {
    // Response shows that user did not grant permission
    app.tell('Sorry, I could not figure out who to pick up.');
  }
}
const actionMap = new Map();
actionMap.set(REQUEST_PERMISSION_ACTION, requestPermission);
actionMap.set(GET_RIDE_ACTION, sendRide);
app.handleRequest(actionMap);

askForPermissions

askForPermissions(context, permissions, dialogState)

Equivalent to askForPermission, but allows you to prompt the user for more than one permission at once.

Notes:

  • The order in which you specify the permission prompts does not matter - it is controlled by the Assistant to provide a consistent user experience.
  • The user will be able to either accept all permissions at once, or none. If you wish to allow them to selectively accept one or other, make several dialog turns asking for each permission independently with askForPermission.
  • Asking for DEVICE_COARSE_LOCATION and DEVICE_PRECISE_LOCATION at once is equivalent to just asking for DEVICE_PRECISE_LOCATION

Parameters

Name Description

context

string

Context why the permission is being asked; it's the TTS prompt prefix (action phrase) we ask the user.

permissions

Array of string

Array of permissions App supports, each of which comes from AssistantApp.SupportedPermissions.

dialogState

Optional

Object

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

Returns

A response is sent to Assistant to ask for the user's permission; for any invalid input, we return null.

Example

const app = new ApiAIApp({request: req, response: res});
const REQUEST_PERMISSION_ACTION = 'request_permission';
const GET_RIDE_ACTION = 'get_ride';

function requestPermission (app) {
  const permission = [
    app.SupportedPermissions.NAME,
    app.SupportedPermissions.DEVICE_PRECISE_LOCATION
  ];
  app.askForPermissions('To pick you up', permissions);
}

function sendRide (app) {
  if (app.isPermissionGranted()) {
    const displayName = app.getUserName().displayName;
    const address = app.getDeviceLocation().address;
    app.tell('I will tell your driver to pick up ' + displayName +
        ' at ' + address);
  } else {
    // Response shows that user did not grant permission
    app.tell('Sorry, I could not figure out where to pick you up.');
  }
}
const actionMap = new Map();
actionMap.set(REQUEST_PERMISSION_ACTION, requestPermission);
actionMap.set(GET_RIDE_ACTION, sendRide);
app.handleRequest(actionMap);

askForSignIn

askForSignIn(dialogState)

Asks user for a timezone-agnostic date and time.

Parameter

Name Description

dialogState

Optional

Object

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

Example

const app = new ApiAiApp({ request, response });
const WELCOME_INTENT = 'input.welcome';
const SIGN_IN = 'sign.in';

function welcomeIntent (app) {
  app.askForSignIn();
}

function signIn (app) {
  if (app.getSignInStatus() === app.SignInstatus.OK) {
    let accessToken = app.getUser().accessToken;
    app.ask('Great, thanks for signing in!');
  } else {
    app.ask('I won\'t be able to save your data, but let\'s continue!');
  }
}

const actionMap = new Map();
actionMap.set(WELCOME_INTENT, welcomeIntent);
actionMap.set(SIGN_IN, signIn);
app.handleRequest(actionMap);

askForTransactionDecision

askForTransactionDecision(order, transactionConfig, dialogState)

Asks user to confirm transaction information.

Parameters

Name Description

order

Object

Order built with buildOrder().

transactionConfig

(ActionPaymentTransactionConfig or GooglePaymentTransactionConfig)

Configuration for the transaction. Includes payment options and order options.

dialogState

Optional

Object

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

Example

const app = new ApiAiApp({request: request, response: response});
const WELCOME_INTENT = 'input.welcome';
const TXN_COMPLETE = 'txn.complete';

let transactionConfig = {
    deliveryAddressRequired: false,
    type: app.Transactions.PaymentType.BANK,
    displayName: 'Checking-1234'
};

let order = app.buildOrder();
// fill order cart

function welcomeIntent (app) {
  app.askForTransaction(order, transactionConfig);
}

function txnComplete (app) {
  // respond with order update
}

const actionMap = new Map();
actionMap.set(WELCOME_INTENT, welcomeIntent);
actionMap.set(TXN_COMPLETE, txnComplete);
app.handleRequest(actionMap);

askForTransactionRequirements

askForTransactionRequirements(transactionConfig, dialogState) returns Object

Checks whether user is in transactable state.

Parameters

Name Description

transactionConfig

(ActionPaymentTransactionConfig or optional GooglePaymentTransactionConfig)

Configuration for the transaction. Includes payment options and order options. Optional if order has no payment or delivery.

dialogState

Optional

Object

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

Returns

Object HTTP response.

Example

const app = new ApiAiApp({request: request, response: response});
const WELCOME_INTENT = 'input.welcome';
const TXN_REQ_COMPLETE = 'txn.req.complete';

let transactionConfig = {
    deliveryAddressRequired: false,
    type: app.Transactions.PaymentType.BANK,
    displayName: 'Checking-1234'
};
function welcomeIntent (app) {
  app.askForTransactionRequirements(transactionConfig);
}

function txnReqCheck (app) {
  if (app.getTransactionRequirementsResult() === app.Transactions.ResultType.OK) {
    // continue cart building flow
  } else {
    // don't continue cart building
  }
}

const actionMap = new Map();
actionMap.set(WELCOME_INTENT, welcomeIntent);
actionMap.set(TXN_REQ_COMPLETE, txnReqCheck);
app.handleRequest(actionMap);

buildBasicCard

buildBasicCard(bodyText) returns BasicCard

Constructs BasicCard with chainable property setters.

Parameter

Name Description

bodyText

Optional

string

Body text of the card. Can be set using setTitle instead.

Returns

BasicCard Constructed BasicCard.

buildCarousel

buildCarousel() returns Carousel

Constructs Carousel with chainable property setters.

Returns

Carousel Constructed Carousel.

buildCart

buildCart(cartId) returns Cart

Constructs Cart with chainable property setters.

Parameter

Name Description

cartId

Optional

string

Unique identifier for the cart.

Returns

Cart Constructed Cart.

buildLineItem

buildLineItem(name, id) returns LineItem

Constructs LineItem with chainable property setters.

Parameters

Name Description

name

string

Name of the line item.

id

string

Unique identifier for the item.

Returns

LineItem Constructed LineItem.

buildList

buildList(title) returns List

Constructs List with chainable property setters.

Parameter

Name Description

title

Optional

string

A title to set for a new List.

Returns

List Constructed List.

buildOptionItem

buildOptionItem(key, synonyms) returns OptionItem

Constructs OptionItem with chainable property setters.

Parameters

Name Description

key

Optional

string

A unique key to identify this option. This key will be returned as an argument in the resulting actions.intent.OPTION intent.

synonyms

(string or optional Array of string)

A list of synonyms which the user may use to identify this option instead of the option key.

Returns

OptionItem Constructed OptionItem.

buildOrder

buildOrder(orderId) returns Order

Constructs Order with chainable property setters.

Parameter

Name Description

orderId

string

Unique identifier for the order.

Returns

Order Constructed Order.

buildOrderUpdate

buildOrderUpdate(orderId, isGoogleOrderId) returns OrderUpdate

Constructs OrderUpdate with chainable property setters.

Parameters

Name Description

orderId

string

Unique identifier of the order.

isGoogleOrderId

boolean

True if the order ID is provided by Google. False if the order ID is app provided.

Returns

OrderUpdate Constructed OrderUpdate.

buildRichResponse

buildRichResponse(richResponse) returns RichResponse

Constructs RichResponse with chainable property setters.

Parameter

Name Description

richResponse

Optional

RichResponse

RichResponse to clone.

Returns

RichResponse Constructed RichResponse.

getSurfaceCapabilities

getSurfaceCapabilities() returns Object

Gets surface capabilities of user device.

Implemented in subclasses for Actions SDK and API.AI.

Returns

Object HTTP response.

getUserName

getUserName() returns UserName

If granted permission to user's name in previous intent, returns user's display name, family name, and given name. If name info is unavailable, returns null.

Returns

UserName Null if name permission is not granted.

Example

const app = new ApiAIApp({request: req, response: res});
const REQUEST_PERMISSION_ACTION = 'request_permission';
const SAY_NAME_ACTION = 'get_name';

function requestPermission (app) {
  const permission = app.SupportedPermissions.NAME;
  app.askForPermission('To know who you are', permission);
}

function sayName (app) {
  if (app.isPermissionGranted()) {
    app.tell('Your name is ' + app.getUserName().displayName));
  } else {
    // Response shows that user did not grant permission
    app.tell('Sorry, I could not get your name.');
  }
}
const actionMap = new Map();
actionMap.set(REQUEST_PERMISSION_ACTION, requestPermission);
actionMap.set(SAY_NAME_ACTION, sayName);
app.handleRequest(actionMap);

handleRequest

handleRequest(handler)

Handles the incoming Assistant request using a handler or Map of handlers. Each handler can be a function callback or Promise.

Parameter

Name Description

handler

(function() or Map)

The handler (or Map of handlers) for the request.

Example

// Actions SDK
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);

// API.AI
const app = new ApiAIApp({request: req, response: res});
const NAME_ACTION = 'make_name';
const COLOR_ARGUMENT = 'color';
const NUMBER_ARGUMENT = 'number';

function makeName (app) {
  const number = app.getArgument(NUMBER_ARGUMENT);
  const color = app.getArgument(COLOR_ARGUMENT);
  app.tell('Alright, your silly name is ' +
    color + ' ' + number +
    '! I hope you like it. See you next time.');
}

const actionMap = new Map();
actionMap.set(NAME_ACTION, makeName);
app.handleRequest(actionMap);

hasSurfaceCapability

hasSurfaceCapability(capability) returns boolean

Returns true if user device has a given surface capability.

Parameter

Name Description

capability

string

Must be one of AssistantApp.SurfaceCapabilities.

Returns

boolean True if user device has the given capability.

Example

const app = new ApiAIApp({request: req, response: res});
const DESCRIBE_SOMETHING = 'DESCRIBE_SOMETHING';

function describe (app) {
  if (app.hasSurfaceCapability(app.SurfaceCapabilities.SCREEN_OUTPUT)) {
    app.tell(richResponseWithBasicCard);
  } else {
    app.tell('Let me tell you about ...');
  }
}
const actionMap = new Map();
actionMap.set(DESCRIBE_SOMETHING, describe);
app.handleRequest(actionMap);