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,
  "availableSurfaces": [
    {
      object(Surface)
    }
  ]
}
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.

availableSurfaces[]

object(Surface)

Surfaces available for cross surface handoff.

User

JSON representation
{
  "userId": string,
  "idToken": string,
  "profile": {
    object(UserProfile)
  },
  "accessToken": string,
  "permissions": [
    enum(Permission)
  ],
  "locale": string,
  "lastSeen": string,
  "userStorage": string,
  "packageEntitlements": [
    {
      object(PackageEntitlement)
    }
  ]
}
Fields
userId
(deprecated)

string

Unique ID for the end user.

idToken

string

Token representing the user's identity. This is a Json web token including encoded profile. The definition is at https://developers.google.com/identity/protocols/OpenIDConnect#obtainuserinfo.

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.

lastSeen

string (Timestamp format)

The timestamp of the last interaction with this user. This field will be omitted if the user has not interacted with the agent before.

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

userStorage

string

An opaque token supplied by the application that is persisted across conversations for a particular user. The maximum size of the string is 10k characters.

packageEntitlements[]

object(PackageEntitlement)

List of user entitlements for every package name listed in action package, if any.

UserProfile

Contains the user's personal info. Fields are only populated if the user user grants the permission to the app for a particular field.

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.

PackageEntitlement

List of entitlements related to a package name

JSON representation
{
  "packageName": string,
  "entitlements": [
    {
      object(Entitlement)
    }
  ]
}
Fields
packageName

string

Should match the package name in action package

entitlements[]

object(Entitlement)

List of entitlements for a given app

Entitlement

Defines a user's digital entitlement. Types of possible entitlements: paid-app,in-app purchases, in-app subscriptions.

JSON representation
{
  "sku": string,
  "skuType": enum(SkuType),
  "inAppDetails": {
    object(SignedData)
  }
}
Fields
sku

string

Product sku. Package name for paid app, suffix of Finsky docid for in-app purchase and in-app subscription. Match getSku() in Play InApp Billing API.

skuType

enum(SkuType)

inAppDetails

object(SignedData)

Only present for in-app purchase and in-app subs.

SignedData

JSON representation
{
  "inAppPurchaseData": {
    object
  },
  "inAppDataSignature": string
}
Fields
inAppPurchaseData

object (Struct format)

Match INAPP_PURCHASE_DATA from getPurchases() method. Contains all inapp purchase data in JSON format See details in table 6 of https://developer.android.com/google/play/billing/billing_reference.html.

inAppDataSignature

string

Matches IN_APP_DATA_SIGNATURE from getPurchases() method in Play InApp Billing API.

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.capability.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
{
  "inputType": enum(InputType),

  // Union field input can be only one of the following:
  "query": string,
  "url": string
  // End of list of possible types for union field input.
}
Fields
inputType

enum(InputType)

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

Union field input. The actual input value input can be only one of the following:
query

string

Typed or spoken input from the end user.

url

string

The triggering URL.