This document goes over how a simple conversation action with fulfillment is built. The sample returns fun facts about Google's history and headquarters, and users unlock an easter egg for cat facts after progressing through enough Google facts.
This sample an shows you how to use the following API.AI components:
This section goes over the intents in this conversation action and their purpose. To view the intents:
- Click on the Intents menu item in the left navigation to view all the intents.
- Click on each of the intents to see its definition and settings.
The following diagram shows you the logic flow of the intents, which control the conversation with the user and calls the fulfillment endpoint to do processing.
Default Welcome Intent
This is the default Welcome intent created by API.AI which is triggered by the Welcome event fired when users trigger your action. Welcome intents typically do things like greet the user, control logic flow and disambiguate the user's initial intent when it's unclear what users want to do. For this sample, it asks whether the user wants to hear about Google’s history or headquarters. This intent also sets an outgoing context called `in_dialog`. This is a flag set once the user is inside the conversation. It is used to differentiate between the fallback handlers.
Unrecognized Deep Link Fallback
This fallback intent acts as the conversation repair mechanism when a user attempts to invoke the action with an unrecognized invocation argument. The fulfillment logic for this intent alerts the user to unrecognized phrase, then redirects them to another intent. This intent requires no incoming context, allowing it to be triggered at invocation time, but sets an outgoing context called in_dialog.
In Dialog Fallback
This fallback intent acts requires an incoming context called in_dialog causing it to be triggered when no other intent is triggered, but only once the user has entered conversation.. Similar to the Unrecognized Deep Link Fallback this intent attempts to continue the conversation naturally with the user.
- This intent defines a parameter named
categoryand assigns it a custom entity of
@fact-category, which defines the two strings
headquarters. When you declare parameters, you tell API.AI that you need specific values from the user to process.
- By assigning the parameter the
@facts-category entity, the action to take for this intent only executes when it can figure out whether the user has spoken
- The parameter is marked as required, so the user is reprompted until they provide speech that contains the parameter.
- This intent uses contexts, which let you interpret and process user speech within a specific scope and to maintain state within that scope.
This intent sets
google_factsto be an output context. This allows any other intent with an input context of
google_factsto access the
categoryparameter. By doing this, you can keep the user in a particular category of facts without asking them after each fact what category they want to hear.
- This intent also sets in_dialog to be an output context. This propagates the context flag used to differentiate between fallback intents.
- By assigning the parameter the
- This intent declares an input context of
google_factto receive the category parameter value. Based on this parameter, it either recites "headquarters" or "history"
- This intent act as a loop when the user says “yes” or “tell me another” after hearing a fact.
- The say_google_fact intent uses the
google-factscontext to obtain the category parameter, so it doesn't need to ask after every fact what fact users want to hear.
choose_cats and say_cat_fact
- These intents work much like
say_cat_fact. However, there are no parameters for these intents because there are no cat fact categories.
- This intent listens for quit commands and exits the entire action.