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 defines the actions in your app. An action defines an entry point into your app by mapping an intent to the corresponding fulfillment endpoint. The intent describes the action to be done, such as booking a ride or asking for the weather. The fulfillment carries out the logic to fulfill the intent by defining the conversation (user interface) that gets the required user input, processing that input, and returning a response back to users.

Default action

Every action package must define one and only one action that handles the actions.intent.MAIN intent. This is the default entry point into your app and this intent is triggered by the Google Assistant when users invoke your app by its name.

For example, this action defines a default action for a Facts about Google app. Users can trigger this intent by saying "Ok Google, talk to Facts about Google".

"actions": [
  {
   "intent": {
        "name": "actions.intent.MAIN"
   },
   "fulfillment": {
      conversationName: "facts-about-google"
    }
  }
]

When this intent is triggered, the fulfillment might return a greeting like, *"Welcome to Facts about Google! Do you want to hear facts about Google's history or headquarters?".

Additional actions

You can define additional actions that give users more specific ways to invoke your app. For example, say you wanted to add another action to a Facts About Google app that allowed users to ask for history facts directly in the initial invocation (for example, "Ok Google, talk to Facts about Google to tell me history facts") For this action, you define your own intent name because this is specific to your app, such as com.example.facts.HISTORY, and specify how the intent is triggered with query patterns.

"actions": [
  {
   "intent": {
        "name": "actions.intent.MAIN"
   },
   "fulfillment": {
      conversationName: "facts-about-google"
    }
  },
  {
   "intent": {
        "name": "com.example.facts.HISTORY",
          "queryPatterns": [    
            {"queryPattern": "tell me history facts"},
            {"queryPattern": "give me some Google history "},
            {"queryPattern": "find some facts about Google's history" }
          ]
   },
   "fulfillment": {
      conversationName: "facts-about-google"
    }
  },
]

As you might have noticed, how you declare entry points into your app is important to how users discover and invoke your app. See the Invocation and Discovery document for more information.

Action package 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"
          ]
        }
      ]
    }
  ]