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

Invocation and Discovery

As described in Invocation and Discovery in the Distribute section of the documentation, you can define how your actions are invoked in the following ways:

  • Invocation name: "talk to Personal Chef", "let me talk to Personal Chef"
  • Deep link invocation: "talk to Personal Chef to find chicken recipes"

You define invocation and discovery patterns in the initialTrigger elements of your actions. When an initialTrigger intent is triggered, a request is sent to the fulfillment endpoint served at httpExecutionUrl. Your Conversation Action then takes over the user experience.

Explicit invocation name

When users invoke your actions by invocation name only, a special assistant.intent.action.MAIN intent is triggered. All action packages must define an action to handle this intent.

For example, if your invocation name is Personal Chef, then this intent is triggered when users say "talk to Personal Chef".

"actions": [
  {
    "description": "Default action",
    "initial_trigger": {
      "intent": "assistant.intent.action.MAIN"
    },
    "http_execution": {
      "url": "..."
    }
  },
  ...
]

See handling the main invocation intent for more information on how to respond to a main invocation intent.

In addition to the main action that handles, you can define "deep link" actions that carry out specialized tasks. For example, "talk to Personal Chef to find dinner recipes"

To let users trigger deep link actions:

  1. Define additional actions in the actions array that correspond to the deep link actions you want users to be able to do.
  2. For each initialTrigger in an action, define query patterns with just the invocation argument. For example, specify only "find dinner recipes" and not "Ok Google, talk to Personal Chef to find dinner recipes".

These query patterns are used by Google for action ranking and discovery. They should be representative of your capabilities and should be how indicate users might want to invoke your actions.

The following example action package snippet shows how to declare a deep link action that finds recipes:

"actions": [
  {
    "description": "Default action",
    "initial_trigger": {
      "intent": "assistant.intent.action.MAIN"
    },
    "http_execution": {
      "url": "..."
    }
  },
  {
    "description": "Deep link that finds recipes",
    "initial_trigger": {
      "intent": "com.personalchef.recipes",
      "queryPatterns": [
        {"queryPattern": "find recipes for $SchemaOrg_Text:word"},
        {"queryPattern": "about $SchemaOrg_Text:word"},
        {"queryPattern": "find dinner recipes"}
      ]
    },
    "http_execution": {
      "url": "..."
    }
  }

For deep link invocation to work, users must say your invocation name and argument when making their initial request with the Google Assistant.

However, if users don't say your invocation name and only the invocation argument, the Google Assistant tries to figure out if one of your actions can handle the user request, as described in Discovery.

Discovery

In some cases, some of an intent's query patterns can trigger your action, even if users don't use your invocation name.

For example, if the user asks “I want recipes”, the Google Assistant may respond with “OK, for that, try saying let me talk to Personal Chef”.

While these hints offer a powerful discovery tool for users, don't be overly general as these patterns are only triggered if the Google Assistant doesn’t know how to handle the user’s query. The Google Assistant will match queries similar to the ones you specify, so an exhaustive list is not recommended. Provide a few examples as hints to the Google Assistant for the kind of action phrases you support. As a result of this expansion, users can say more phrases than just the examples you give in the action package.

Of course, these query patterns are not unique to your agent and therefore the Google Assistant will determine which agent (or agents) to suggest for users. This determination is based on what's best for the user.