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

Define Actions

To define actions in API.AI, you create intents in your API.AI agent and assign them as entry points into your app. You can create the following types of actions:

  • Default action: Every API.AI agent must have one and only one action that's invoked when users ask for your app by name (for example "Ok, Google. Talk to Facts about Google" or "Ok, Google. Let me talk to Facts about Google")
  • Additional actions to deep link into your app: These actions are triggered when users invoke your app by its name and specify an action (for example "talk to Facts about Google for history facts").

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

Define a default action

Every API.AI agent must have one and only one intent that handles the GOOGLE_ASSISTANT_WELCOME event. This intent is triggered when users invoke by app name (for example, "Ok Google, talk to Facts about Google").

You can define the GOOGLE_ASSISTANT_WELCOME event in the following ways:

From the intent editor:

  1. Click on Intents in the left navigation.
  2. Select the intent that you want to set the welcome event for.
  3. In the Events section of the intent editor, enter GOOGLE_ASSISTANT_WELCOME.

From the Actions on Google integration screen:

  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 the welcome event for. When you view the intent in the intent editor, you should see that API.AI automatically sets the GOOGLE_ASSISTANT_WELCOME event.

You'll most likely want to enable fulfillment for the intent as well. When an intent is triggered, fulfillment processes the intent and returns a response. By default, API.AI doesn't call your fulfillment and can return static responses. This might be enough for simple actions or ones that always respond with the same message when invoked. You can specify static responses in the Response area of the intent if you don't need fulfillment to generate the response.

To enable fulfillment for the welcome intent:

  1. Scroll to the bottom of the intent editor for your welcome intent.
  2. Click Fulfillment and select Use webhook.

See Build Fulfillment for information on how to handle this intent when it's triggered.

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 Facts about Google to find me history facts").

To define additional actions in API.AI:

  1. Create an intent for each action that you want to create.
  2. Declare the patterns that trigger the action in the User says field. For example, if you want users to be able to say the following action invocation:

    • Invocation 1: "talk to Facts about Google to find me history facts"

    you'd declare an intent with User says phrases like:

    "find me history facts", "look up history facts", "get me facts about history of the company", "read me some headquarters facts", "tell me a few facts about its headquarters"

    We recommend around 10 User says phrases for each intent that defines an action.

  3. To enable fulfillment for the welcome intent, scroll to the bottom of the intent editor for your welcome intent, click Fulfillment, and select Use webhook.

    See Build Fulfillment for information on how to handle this intent when it's triggered.

  4. Once you have the intent that you want to use for action invocation, you need to set them as Additional triggering 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.

When defining actions, the following restrictions and guidelines apply:

  • Don't specify "reserved" wording from name invocation or action invocation and "trigger phrases". For example, don't use "talk to <app 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.

Handling unrecognized actions when users invoke your app

When users say specify an action that your app 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 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 Build Responses for more information on how to handle intents in your fulfillment.