AppRequest

AppRequest is a request sent by the Google Assistant to a fulfillment in order to interact with an Action. 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. For examples of how this is used in actions on Google, see https://developers.google.com/assistant/actions/build/json/conversation-webhook-json .

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 Action.

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 Action. 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
{
  "idToken": string,
  "profile": {
    object (UserProfile)
  },
  "accessToken": string,
  "permissions": [
    enum (Permission)
  ],
  "locale": string,
  "lastSeen": string,
  "userStorage": string,
  "packageEntitlements": [
    {
      object (PackageEntitlement)
    }
  ],
  "userVerificationStatus": enum (UserVerificationStatus)
}
Fields
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 Action.

accessToken

string

An OAuth2 token that identifies the user in your system. Only available if the user links their account.

permissions[]

enum (Permission)

Contains permissions granted by user to this Action.

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 the Action package, if any.

userVerificationStatus

enum (UserVerificationStatus)

Indicates the verification status of the user.

UserProfile

Contains the user's personal info. Fields are only populated if the user user grants the permission to the Action 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 Action.

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

object (Location)

Represents actual device location such as latitude, longitude, 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 lifecycle.

conversationToken

string

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

Input

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

object (RawInput)

Raw input transcription from each turn of conversation. Multiple conversation turns may be required for actions on Google to provide some types of input to the Action.

intent

string

Indicates the user's intent. For the first conversation turn, the intent will refer to the triggering intent for the Action. For subsequent conversation turns, the intent will be a common actions on Google intent (starts with 'actions.'). 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. See https://developers.google.com/assistant/conversational/reference/rest/intents.

arguments[]

object (Argument)

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

canvasState

object (Struct format)

Opaque context set in the interactive canvas web app for all subsequent intents

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.