AppRequest

AppRequest is sent by the Google Assistant to apps to ask for the app to drive feature-specific conversations. The API version is specified in the HTTP header. For API version 1, the header contains: Google-Assistant-API-Version: v1. For API version 2, the header contains: Google-Actions-API-Version: 2.

JSON representation
{
  "user": {
    object(User)
  },
  "device": {
    object(Device)
  },
  "surface": {
    object(Surface)
  },
  "conversation": {
    object(Conversation)
  },
  "inputs": [
    {
      object(Input)
    }
  ],
  "isInSandbox": boolean,
}
Fields
user

object(User)

User who initiated the conversation.

device

object(Device)

Information about the device the user is using to interact with the app.

surface

object(Surface)

Information about the surface the user is interacting with, e.g. whether it can output audio or has a screen.

conversation

object(Conversation)

Holds session data like the conversation ID and conversation token.

inputs[]

object(Input)

List of inputs corresponding to the expected inputs specified by the app. For the initial conversation trigger, the input contains information on how the user triggered the conversation.

isInSandbox

boolean

Indicates whether the request should be handled in sandbox mode.

User

JSON representation
{
  "userId": string,
  "profile": {
    object(UserProfile)
  },
  "accessToken": string,
  "permissions": [
    enum(Permission)
  ],
  "locale": string,
}
Fields
userId

string

Unique ID for the end user.

profile

object(UserProfile)

Information about the end user. Some fields are only available if the user has given permission to provide this information to the app.

accessToken

string

An OAuth2 token that identifies the user in your system. Only available if [Account Linking][google.actions.v2.AccountLinking] configuration is defined in the action package and the user links their account.

permissions[]

enum(Permission)

Contains permissions granted by user to this app.

locale

string

Primary locale setting of the user making the request. Follows IETF BCP-47 language code http://www.rfc-editor.org/rfc/bcp/bcp47.txt However, the script subtag is not included.

UserProfile

Contains the user's personal info. It's accessible only after user grants the permission to the app.

JSON representation
{
  "displayName": string,
  "givenName": string,
  "familyName": string,
}
Fields
displayName

string

The user's full name as specified in their Google account. Requires the NAME permission.

givenName

string

The user's first name as specified in their Google account. Requires the NAME permission.

familyName

string

The user's last name as specified in their Google account. Note that this field could be empty. Requires the NAME permission.

Device

Information about the device the user is using to interact with the Google Assistant.

JSON representation
{
  "location": {
    object(Location)
  },
}
Fields
location

object(Location)

Represents actual device location such as lat, lng, and formatted address. Requires the DEVICE_COARSE_LOCATION or DEVICE_PRECISE_LOCATION permission.

Surface

Information specific to the Google Assistant client surface the user is interacting with. Surface is distinguished from Device by the fact that multiple Assistant surfaces may live on the same device.

JSON representation
{
  "capabilities": [
    {
      object(Capability)
    }
  ],
}
Fields
capabilities[]

object(Capability)

A list of capabilities the surface supports at the time of the request e.g. actions.capability.AUDIO_OUTPUT

Capability

Represents a unit of functionality that the surface is capable of supporting.

JSON representation
{
  "name": string,
}
Fields
name

string

The name of the capability, e.g. actions.capabililty.AUDIO_OUTPUT

Conversation

JSON representation
{
  "conversationId": string,
  "type": enum(ConversationType),
  "conversationToken": string,
}
Fields
conversationId

string

Unique ID for the multi-turn conversation. It's assigned for the first turn. After that it remains the same for subsequent conversation turns until the conversation is terminated.

type

enum(ConversationType)

Type indicates the state of the conversation in its life cycle.

conversationToken

string

Opaque token specified by the app in the last conversation turn. It can be used by an app to track the conversation or to store conversation related data.

Input

JSON representation
{
  "rawInputs": [
    {
      object(RawInput)
    }
  ],
  "intent": string,
  "arguments": [
    {
      object(Argument)
    }
  ],
}
Fields
rawInputs[]

object(RawInput)

Raw input transcription from each turn of conversation that was used to provide this input. Multiple conversation turns that don't involve the app may be required for the assistant to provide some types of input.

intent

string

Indicates the user's intent. For the first conversation turn, the intent will refer to the intent of the action that is being triggered. For subsequent conversation turns, the intent will be a built-in intent. For example, if the expected input is actions.intent.OPTION, then the the intent specified here will either be actions.intent.OPTION if the Google Assistant was able to satisfy that intent, or actions.intent.TEXT if the user provided other information.

arguments[]

object(Argument)

A list of provided argument values for the input requested by the app.

RawInput

JSON representation
{
  "createTime": string,
  "inputType": enum(InputType),
  "query": string,
}
Fields
createTime

string (Timestamp format)

When the user provided this input.

A timestamp in RFC3339 UTC "Zulu" format, accurate to nanoseconds. Example: "2014-10-02T15:01:23.045123456Z".

inputType

enum(InputType)

Indicates how the user provided this input: a typed response, a voice response, unspecified, etc.

query

string

Typed or spoken input from the end user.

Argument

JSON representation
{
  "name": string,
  "rawText": string,

  // Union field value can be only one of the following:
  "boolValue": boolean,
  "textValue": string,
  "datetimeValue": {
    object(DateTime)
  },
  "extension": {
    "@type": string,
    field1: ...,
    ...
  },
  // End of list of possible types for union field value.
}
Fields
name

string

Name of the argument being provided for the input.

rawText

string

The raw text, typed or spoken, that provided the value for the argument.

Union field value. One of the following is specified. value can be only one of the following:
boolValue

boolean

Specified when query pattern includes a $org.schema.type.YesNo type or expected input has a built-in intent: actions.intent.CONFIRMATION. NOTE: if the boolean value is missing, it represents false.

textValue

string

Specified when query pattern includes a $org.schema.type.Text type or expected input has a built-in intent: actions.intent.TEXT, or actions.intent.OPTION. Note that for the OPTION intent, we set the textValue as option key, the rawText above will indicate the raw span in user's query.

datetimeValue

object(DateTime)

Specified for the built-in intent: actions.intent.DATETIME.

extension

object

Extension whose type depends on the argument. For example, if the argument name is SIGN_IN for the actions.intent.SIGN_IN intent, then this extension will contain a SignInValue value.

An object containing fields of an arbitrary type. An additional field "@type" contains a URI identifying the type. Example: { "id": 1234, "@type": "types.example.com/standard/id" }.

DateTime

Date and time argument value parsed from user input. Does not include time zone information.

JSON representation
{
  "date": {
    object(Date)
  },
  "time": {
    object(TimeOfDay)
  },
}
Fields
date

object(Date)

Date value

time

object(TimeOfDay)

Time value

Date

Represents a whole calendar date, e.g. date of birth. The time of day and time zone are either specified elsewhere or are not significant. The date is relative to the Proleptic Gregorian Calendar. The day may be 0 to represent a year and month where the day is not significant, e.g. credit card expiration date. The year may be 0 to represent a month and day independent of year, e.g. anniversary date. Related types are google.type.TimeOfDay and google.protobuf.Timestamp.

JSON representation
{
  "year": number,
  "month": number,
  "day": number,
}
Fields
year

number

Year of date. Must be from 1 to 9999, or 0 if specifying a date without a year.

month

number

Month of year. Must be from 1 to 12.

day

number

Day of month. Must be from 1 to 31 and valid for the year and month, or 0 if specifying a year/month where the day is not significant.

TimeOfDay

Represents a time of day. The date and time zone are either not significant or are specified elsewhere. An API may choose to allow leap seconds. Related types are google.type.Date and google.protobuf.Timestamp.

JSON representation
{
  "hours": number,
  "minutes": number,
  "seconds": number,
  "nanos": number,
}
Fields
hours

number

Hours of day in 24 hour format. Should be from 0 to 23. An API may choose to allow the value "24:00:00" for scenarios like business closing time.

minutes

number

Minutes of hour of day. Must be from 0 to 59.

seconds

number

Seconds of minutes of the time. Must normally be from 0 to 59. An API may allow the value 60 if it allows leap-seconds.

nanos

number

Fractions of seconds in nanoseconds. Must be from 0 to 999,999,999.