Invocation and Discovery

Our goal is to give users a natural way to invoke Assistant apps, and we provide several invocation patterns that users can use to invoke your actions.

Invocation components

To understand the possible invocation patterns, let's start by defining the possible components of an invocation command.

Trigger phrase

These phrases start an invocation and are defined by Actions on Google. They can be things like:

  • "Ok Google, talk to..."
  • "Ok Google, speak to..."
  • "Ok Google, I want speak to..."
  • "Ok Google, ask..."

App Name

This is the name of your app, such as "Personal Chef". Users combine this with trigger phrases to invoke apps by name, such as: "Ok Google, let me talk to Personal Chef". This type of invocation is called app invocation.

Action phrase

Action phrases are a valuable mechanism to increase the discoverability of your app, and provide a way for users to deep link into your app by providing an action to perform. These phrases illustrate various ways users might request your app's features, so the Assistant can better understand your app's capabilities and match your app's actions with user requests.

  • "find me recipes"
  • "recommend a wine"
  • "book a ride"
  • "play a game"
  • "want to meditate"

Users combine your app name with action phrases to explicitly invoke specific actions. For example: "Ok Google, talk to Personal Chef to find me recipes". This is called action invocation.

App invocation

Your app name is unique to your app and is the primary way that users invoke your app. As such, it's extremely important that you pick a good one. If your app name is hard to pronounce, sounds like other words, or can not be recognized well by Google, then it's likely that users will be consistently unable to invoke your app.

See the naming policies document for restrictions and guidelines for an app name.

The following trigger phrases are supported by default by Actions on Google:

  • "let me talk to $name"
  • "I want to talk to $name"
  • "can I talk to $name"
  • "talk to $name"
  • "let me speak to $name"
  • "I want to speak to $name"
  • "can I speak to $name"
  • "speak to $name"

You don't need to specify anything to support these invocations and you can expect other similar patterns to work as well.

App invocation intent

When app invocation occurs, the actions.intent.MAIN intent in your app is triggered. Your app must contain one and only one default action that handles this intent. See the intents documentation for more information about intents and define a default action with API.AI or define a default action with Actions SDK for more information on creating actions.

Action invocation and discovery

You can also let users deep link into your app by invoking specific actions when they know what they want to do and the action phrase to say. The usage patterns that are supported are natural variations of the following patterns:

  • Let me talk to $name about $action_phrase
  • Talk to $name about $action_phrase
  • Can I talk to $name about $action_phrase
  • I want to talk to $name about $action_phrase
  • Let me speak to $name about $action_phrase
  • Speak to $name about $action_phrase
  • Can I speak to $name about $action_phrase
  • I want to speak to $name about $action_phrase

For example, users can say: "Talk to Best New York Pizza to order a pepperoni pizza". This invocation combines the app name and action phrase to explicitly invoke the app and deep link into the action.

Another way these action phrases help us through action discovery. Action discovery occurs when the Assistant matches invocations that have an action phrase without an app name. For example, if the user says "Ok Google, I want some authentic New York pizza", the Google Assistant may respond with "Ok, for that, try saying let me 'talk to Best New York Pizza'".

Providing good action phrases

Action phrases offer a helpful invocation and discoverability tool for users, but you must choose them carefully. These phrases must be specific to the actions they’re associated with, or the Assistant won't be able to match user queries, because the phrases are too general.

Bad action phrases

  • Lacks a verb - “easy recipe”
  • Too general - “public transit”

Good action phrases

  • Has a clear verb and object - hear a dad joke"
  • Provides specific requests:
    • "what is my horoscope for today"
    • "hear a fun fact"
    • "give me a 5 minute workout"
    • "what should I wear today"
    • "get me a rental car"
    • "I need a hotel room"
    • "buy concert tickets"
    • "coupons that expire today"

Of course, these action phrases are not unique to your app and therefore the Google Assistant determines which apps to suggest for users.

Action invocation intents

You define your own intents and action phrases for action invocation. See the intents documentation for more information about intents and define additional actions with API.AI or define additional actions with Actions SDK for more information on creating actions.