This document describes the HTTP/JSON API for communicating between Google Assistant and a fulfillment service that defines a custom conversational user interface.
It's important to understand how the Assistant and your fulfillment communicate via HTTP/JSON:
- To participate in conversations with the Assistant, your fulfillment implements a webhook that can respond to HTTP requests from the Assistant.
- When users invoke your Action through the Assistant, your fulfillment receives an
HTTP POSTwith a JSON payload that describe's the user's request.
- In turn, your fulfillment is responsible for reading the parameters from the request payload, generating an appropriate JSON formatted response, and sending a reply to the Assistant with this response.
This table summarizes the types of requests that your webhook might receive from the Assistant:
|Invocation requests||User utterances that initiate the conversation with your fulfillment
or trigger deep-link Actions (for example, "Talk to Personal Chef to
find dinner recipes").
|Conversation requests||Utterances by users in the same session once the conversation with your fulfillment has
started. In the conversation webhook format, these are the raw text responses from the
user corresponding to
|Helper results||Requests sent by the Assistant to your fulfillment when your webhook has
requested an helper intent in the
previous turn of the conversation to handle parts of the
conversation (for example,
Conversation requests and responses
In a typical Google Assistant interaction scenario, users utter a phrase to invoke an Action. To provide a response, Actions on Google finds the fulfillment that matches the Action invoked by the user and sends the request there.
Once Actions on Google establishes that your fulfillment is a suitable match for the user's invocation, it starts a conversation session by sending an HTTP request that contains a JSON payload with the user's request information to your fulfillment endpoint. Your fulfillment parses the request and returns a response that contains a JSON payload. The Assistant then converts the payload into rendered speech and multimedia output for users.
To learn more about the format of the JSON payload when Actions on Google invokes your fulfillment through the Actions SDK, see Conversation Webhook Format.
Dialogflow requests and responses
If you are creating Actions, you can optionally use Dialogflow to simplify the task of building conversational interfaces. In this scenario, Dialogflow acts as a proxy between Actions on Google and your fulfillment. Instead of sending the HTTP/JSON request directly to your fulfillment endpount, Actions on Google sends it to Dialogflow.
Dialogflow wraps the JSON payload contained in the original request into the Dialogflow webhook format, and forwards the resulting request to your fulfillment.
Conversely, when your fulfillment sends a response to Dialogflow, the JSON payload of the response must comply with the Dialogflow webhook format. Your fulfillment parses the parameters from the Dialogflow JSON request, and generates a response in the Dialogflow webhook format. Dialogflow then converts the response from your fulfillment into a response message that the Assistant understands.
To learn more about the format of the JSON payload when Actions on Google invokes your fulfillment through Dialogflow, see Dialogflow Webhook Format.