Join the Actions on Google Developer Challenge to win a trip to Google I/O 2018 and more than 20 other prizes.

Action Package

An action package is a JSON file that describes a set of actions that can fulfill a user's intents. A given version of an agent is represented by a single action package. You can preview and submit an action package with the gactions command-line interface.

Example

{
  "versionLabel": "guess a number V1",
  "agentInfo": {
    "languageCode": "en-US",
    "projectId": "PROJECT_ID",
    "voiceName": "male_1"
  },
  "actions": [
    {
      "description": "Launch intent",
      "initialTrigger": {
        "intent": "assistant.intent.action.MAIN"
      },
      "httpExecution": {
        "url": "HTTPS_URL"
      }
    },
    {
      "description": "guess a number game",
      "initialTrigger": {
        "intent": "START_GUESS_NUMBER",
        "queryPatterns": [
          {
            "queryPattern": "find a magic number"
          },
          {
            "queryPattern": "guess a number"
          }
        ]
      },
      "httpExecution": {
        "url": "HTTPS_URL"
      }
    }
  ]
}

Schema reference

ActionPackage

Represents information (metadata) and the actions that can be completed by an agent.

Field Type Description
versionLabel String (Required) indicates the developer friendly label for this action package.
agentInfo AgentInfo (Required) metadata describing the actions in this action package like the Google Project ID and language code.
actions Array of Action (Required) list of conversation actions specified in this action package.

AgentInfo

Metadata describing the actions in this action package like the Google Project ID and language code.

Field Type Description
languageCode String The BCP-47 language code, such as "en-US" or "sr-Latn". As of Oct 2016, we only support en-US.
projectId String Google developer project ID associated with this action package. Used for deployment
voiceName String (Optional) Specifies the voice of the agent. Possible values are:

  • male_1
  • male_2
  • female_1
  • female_2
logoUrl String (Optional) Specifies a logo image for the Action. Required when accountLinking is enabled.
accountLinking AccountLinking (Optional) Specifies the OAuth configuration for account linking between user's Google account and account hosted on your web application.

Action

Describes a conversation action.

Field Type Description
description String (Optional) Short description (less than 100 chars in ASCII) describing the action.
initialTrigger Trigger Defines the initial triggering intent.
execution httpExecution Specifies the URI of the endpoint where Assistant will send the HTTP request. The endpoint must use the https protocol.

Trigger

A trigger contains an intent and associated query patterns which are used as implicit invocations for the action.

Field Type Description
intent String This defines the ID for the intent, used by the endpoint to identify which action has been triggered.
queryPatterns List of QueryPattern List of example query patterns for deep-link invocations and discovery.

QueryPattern

An annotated instance of a developer provided example of a user's speech input.

Field Type Description
queryPattern String Query pattern that should be recognized. The Assistant may match phrases that are semantically similar using Natural Language Processing.

HttpExecution

Sets the URL of the agent endpoint.

Field Type Description
url String HTTP URL of the agent endpoint

AccountLinking

Specifies the OAuth configuration for account linking between user's Google account and account hosted on your web application.

Field Type Description
clientId String Unique public string used to identify client requesting for authentication.
clientSecret String Secret used by authentication server to authorize client.
grantType String OAuth 2.0 flow for Google to use with your server. IMPLICIT_GRANT and AUTH_CODE_GRANT are supported. See OAuth 2.0 Account Linking Overview for more information.
authenticationUrl String URL where customers will be redirected to enter login credentials.
accessTokenUrl String URL to fetch access token given an authentication.
scopes List of String List of scopes user needs to grant permission for, <= 10 scopes are supported.

Query patterns

A query pattern suggests to the Assistant Platform an example phrases a user might say. The Assistant Platform may match user spoken phrases that are semantically similar using Natural Language Processing.

Query patterns can contain a literal string, conditionals, and arguments using Schema.org types.

Literal string

A query pattern can contain a literal string.

Example: "Start the guess the number game."

Conditionals

Portions of a query pattern can be considered optional. To indicate conditional query patterns, wrap the portion of the phrase in parenthesis and end it with a question mark. The following example defines Start the as optional:

Example: "(Start the)? Guess the number game"

Arguments

A query pattern can collect a portion of the user’s input through the use of named arguments (this can also be considered variables). Arguments are specified using the syntax: $Type:argument_name.

Example: "$SchemaOrg_number:number" describes a query pattern that expects an input of a Schema.org number, and that the actual number the user says will be captured in an argument named “number”.

Schema.org types

Following is the list of supported Schema.org types used for query patterns:

Type Example Query Pattern Example User Query
$SchemaOrg_Date read my sms from $SchemaOrg_Date:my_date on sms pro read my sms from april 1st on sms pro
$SchemaOrg_Number blink the flashlight $SchemaOrg_Number:number times blink the flashlight five times
$SchemaOrg_Time read my sms from $SchemaOrg_Time:my_time on sms pro read my sms from 5 pm on sms pro
$SchemaOrg_DayOfWeek show me my meetings on$SchemaOrg_DayOfWeek:day_of_week show me my meetings on Tuesday
$SchemaOrg_Color turn on the $SchemaOrg_Color:my_color strobe light turn on the red strobe light
$SchemaOrg_priceCurrency show conversion rate for $SchemaOrg_priceCurrency:cur on currency app show conversion rate for yen on currency app
$SchemaOrg_Distance show conversion chart for $SchemaOrg_Distance:dist show conversion chart for kilometer
$SchemaOrg_Temperature set temperature to $SchemaOrg_Number:num degrees$SchemaOrg_Temperature:temp set temperature to 70 degrees fahrenheit
$SchemaOrg_Organization watch $SchemaOrg_Organization:organization highlights watch lakers highlights
show me stock price for$SchemaOrg_Organization:organization show me stock price for Google
$SchemaOrg_Person show top 10 $SchemaOrg_Person:musician songs show top 10 bruno mars songs
show me news about $SchemaOrg_Person:person show me news about bill gates
$SchemaOrg_Place write review for $SchemaOrg_Place:place write review for new york
show traffic on $SchemaOrg_Place:location show traffic on mountain view
$SchemaOrg_Product write review for $SchemaOrg_Product:product write review for google glass
$SchemaOrg_Book read $SchemaOrg_Book:my_book read great expectations
$SchemaOrg_Movie play the $SchemaOrg_Movie:my_movie movie review the casablanca movie
$SchemaOrg_TVSeries play next episode of $SchemaOrg_TVSeries:tv_series play next episode of friends
$SchemaOrg_servesCuisine show $SchemaOrg_servesCuisine:my_cuisine restaurants show italian restaurants
$SchemaOrg_MusicAlbum add $SchemaOrg_MusicAlbum:album to my queue. add abbey road to my queue
$SchemaOrg_MusicRecording add $SchemaOrg_MusicRecording:song to my favorites. add with or without you to my favorites.
$SchemaOrg_YesNo $SchemaOrg_YesNo Yes
$SchemaOrg_URL Add $SchemaOrg_URL Add google.com
$SchemaOrg_Email Add $SchemaOrg_Email Add john@google.com
$SchemaOrg_PhoneNumber Add $SchemaOrg_PhoneNumber Add (777) 777-7777
$SchemaOrg_Text What's that song where they say $SchemaOrg_Text What's that song where they say you are my sunshine?

Custom types

Custom types allow you to define your own types, which are a collection of items, the possible ways that user might say an item (synonyms), and the corresponding argument value (key). This lets you define custom

The following example defines a custom type for the different ways a person might say "6am".

"customTypes": [
    {
      "name": "$MorningOptions",
      "items": [
        {
          "key": "6am",
          "synonyms": [
            "6 am",
            "6 o clock",
            "oh six hundred",
            "6 in the morning"
          ]
        }
      ]
    }
  ]