Invocation and Discovery

As decribed in Invocation and Discovery in the Distribute section, 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"

Enabling Actions on Google

Before you can define invocation name and deep link invocation intents, enable the Actions on Google integration by clicking on Integrations in the left navigation of API.AI and moving the Actions on Google slider bar to the right.

Invocation name intents

Every agent must have one and only one intent that handles the GOOGLE_ASSISTANT_WELCOME event. This intent is triggered when users invoke your API.AI agent by invocation name (for example, "talk to Personal Chef").

To mark an intent as the welcome intent:

  1. Click on Integrations in the left navigation and then click the Actions on Google card. The Actions on Google view displays.
  2. In the Welcome Intent field, select the intent that you want to set as the welcome intent. When you view the intent, you should see that API.AI automatically sets the GOOGLE_ASSISTANT_WELCOME event for this intent.

Deep link invocation intents help disambiguate user requests by letting users specify more details about their request (for example, "talk to Personal Chef to find me recipes").

When defining deep link invocation intents, the following restrictions and guidelines apply:

  • Don't specify "reserved" wording from name invocation or deep link invocation and "trigger phrases". For example, don't use "talk to <invocation name>", "talk to", "let me talk to", etc.
  • Don't specify User says phrases that contain only a @sys.any entity. You should be much more specific, such as find recipes for @sys.any. A User says phrase of only @sys.any is valid for only the welcome intent.

To define deep link intents in API.AI:

  1. Create an intent for each deep link action that you'd like.
  2. Declare the patterns that trigger the deep links in the User says field. For example, if you want users to be able to say use the following deep link invocations:

    • Invocation 1: "talk to Personal Chef to find me <ingredient> recipes"
    • Invocation 2: "speak to Personal Chef to read my food shopping list"

    you'd declare two intents with User says phrases like:

    • Intent 1: "find me chicken recipes", "look up cookie recipes", "get me cannoli recipes".
    • Intent 2: "read my shopping list", "tell me my shopping list"

    You will most likely want to set chicken, cookie, and cannoli as a parameter, such as @sys.any:ingredient, so that API.AI can detect any type of ingredient and not just chicken, cookie, and cannoli. We also recommend around 10 User says phrases for each deep link invocation.

  3. Once you have the deep link intents that you want to use for invocation, you need to set them as deep link intents in API.AI:

    1. Click on Integrations in the left navigation and then click the Actions on Google card. The Actions on Google view displays.
    2. In the Additional triggering intents area, add all the deep link invocation intents that you created.

You can now test your agent with these invocation patterns in the Google Home web simulator or on a Google Home device that is logged in with the same Google account.

Fallback responses

API.AI allows you to handle cases where users speak something that doesn't match a User says phrases in an intent with "fallback intents", or an intent that matches on any input for a given context, assuming that no other specific intent was matched. API.AI creates a default fallback intent for all new agents that you create.

When users use an action phrase for deep link invocation that your agent doesn't recognize, API.AI can trigger a specific fallback intent to handle these cases. To enable this behavior, create a fallback intent that sets an input context to be google_assistant_welcome and specify the appropriate responses to users:

  1. In the left navigation of API.AI, click Intents.
  2. Click the menu item by the Create Intent button and select Create Fallback Intent.
  3. In the Contexts section, specify google_assistant_welcome as the input context. Make sure you hit the Enter key so the context is properly set.
  4. Specify responses that are appropriate for an unrecognized action phrase in the Response section.
  5. If you want to use fulfillment to handle this intent:
    1. In the Action section, specify an action name.
    2. Click the Fulfillment section header and select Use webhook.
    3. When API.AI triggers this intent, you can call the getRawInput() method of the client library to obtain the unrecognized action phrase. You can then return responses in your fulfillment logic based on the unrecognized action phrase or other logic. See building response dialogs for more information.

Enabling fulfillment

For most intents that you create, you'll probably want to enable fulfillment (referred to as a webhook in API.AI). When an intent is triggered, the webhook processes the input and returns a response. See dialogs and fulfillment for more information.

For very simple actions, you might not need any fulfillment at all, because API.AI has built in speech responses that you can define in the Response area of the intent.