Actions on Google HTTP/JSON API

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 POST with 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.

Request types

This table summarizes the types of requests that your webhook might receive from the Assistant:

Type Description JSON Examples
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").
  • If using Dialogflow, these requests correspond to the intents defined in the Discovery section of the Google Assistant integration settings.
  • If using the Actions SDK, these requests correspond to the intents defined in your Action package.
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 actions.intent.TEXT intents that your fulfillment requested in the previous turn.
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, actions.intent.OPTION and actions.intent.PERMISSION).

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.

Figure 1. Actions on Google invoking your fulfillment through the Actions SDK.

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.

Figure 2. Actions on Google invoking your fulfillment through Dialogflow.

To learn more about the format of the JSON payload when Actions on Google invokes your fulfillment through Dialogflow, see Dialogflow Webhook Format.