Define Actions

Actions are entry points into your app that define the invocation and discovery model for your app. You declare actions in a JSON file called an action package, which you eventually upload to your developer project when you want to test or submit your app for approval.

To define actions in your action package, you create an intent that defines how the action is invoked and the corresponding fulfillment endpoint for when the intent is triggered. You can create the following types of actions:

  • Default action: Every app must have one and only one default action that Actions on Google triggers when users request the app by name (for example "Ok Google, talk to Sekai"). This action declares support for the actions.intent.MAIN intent.

  • Additional actions to deep-link into your app: You can create additional actions in your action package with intents that you define yourself. These intents trigger "deep-link" actions in your app, allowing users to invoke specific functionality, such as "Ok Google, talk to Sekai to find some sneakers".

See Invocation and Discovery for more information on how these invocation models work.

Define a default action

Every action package must have one and only one intent that handles the actions.intent.MAIN intent. This intent is triggered when users invoke your app by name (for example, "Ok Google, talk to Sekai").

{
  "actions": [
    {
      "name": "MAIN",
      "intent": {
        "name": "actions.intent.MAIN"
      },
      "fulfillment": {
        "conversationName": "sekaiApp"
      }
    }
  ],
  "conversations": {
    "sekaiApp": {
      "name": "sekaiApp",
      "url": "https://sekai.example.com/sekaiApp"
    }
  }
}

Define additional actions

You can provide additional actions that act as entry points into your app. This lets users disambiguate their intent by letting them specify more details about what they want to do (for example, "talk to Sekai to find me some sneakers").

To define additional actions:

  1. In the actions array, specify an action for every entry point into your app. For example, the following sample shows an additional "buy" action that defines:

    • An intent name of com.example.sekai.BUY
    • parameters to parse from the user input when this intent is triggered. This is useful if you need specific data from the action phrase when users invoke the app.
    • queryPatterns that define what users need to say to trigger the intent, which can include Schema.org types that define parameters to parse.

      {
        "actions": [
          ...
          {
            "name": "BUY",
            "intent": {
              "name": "com.example.sekai.BUY",
              "parameters": [{
                "name": "color",
                "type": "SchemaOrg_Color"
              }],
              "trigger": {
                "queryPatterns": [
                  {"queryPattern": "find some $SchemaOrg_Color:color sneakers"},
                  {"queryPattern": "buy some blue suede shoes"},
                  {"queryPattern": "get running shoes" }
                ]
              }
            },
            "fulfillment": {
              "conversationName": "sekaiApp"
            }
          }
        ]
      }
      
  2. Specify the fulfillment for this intent by specifying a conversationName that corresponds to an item in the conversations object.

    {
      "actions":[
        ...
      ],
      "conversations": {
        "sekaiApp": {
          "name": "sekaiApp",
          "url": "https://sekai.example.com/sekaiApp",
          "fulfillmentApiVersion": 2
        }
      }
    }
    

Here's an example of a full action package:

{
  "actions": [
    {
     "name": "MAIN",
     "intent": {
       "name": "actions.intent.MAIN"
     },
     "fulfillment": {
       "conversationName": "sekaiApp"
     }
    },
    {
      "name": "BUY",
      "intent": {
        "name": "com.example.sekai.BUY",
        "parameters": [{
          "name": "color",
          "type": "SchemaOrg_Color"
        }],
        "trigger": {
          "queryPatterns": [
            {"queryPattern": "find some $SchemaOrg_Color:color sneakers"},
            {"queryPattern": "buy some blue suede shoes"},
            {"queryPattern": "get running shoes" }
          ]
        }
      },
      "fulfillment": {
        "conversationName": "sekaiApp"
      }
    }
  ],
  "conversations": {
    "sekaiApp": {
      "name": "sekaiApp",
      "url": "https://sekai.example.com/sekaiApp",
      "fulfillmentApiVersion": 2
    }
  }
}