Conversation Webhook Format

This section describes the format of the JSON payload when Actions on Google invokes your
fulfillment through the Actions SDK.

Once a conversation starts, it's identified by a unique conversationId. For each subsequent user
query to the Assistant, your fulfillment receives an intent that
your webhook must process and respond to. This conversationIdis persisted in every request and
response pair until the conversation ends.

Request body

When users make an initial query or provide some subsequent input, the Assistant sends a request
to your fulfillment. Conversation webhook requests
from the Assistant contain data such as the intent that was triggered, the raw text of the user
input, and the surface capabilities of the user's device.

The key fields for a request in the conversation webhook format are summarized below:

This boolean variable is primarily used to for the
transactions feature, to indicate whether your webhook should handle this request in sandbox
mode. In sandbox mode, your webhook should not charge or fulfill any purchase orders by users.
By default, it is set to "true".

Information about the invocation request. For the triggering invocation, this includes an
intent] that maps to an action. For subsequent
requests in a conversation, this object might also include arguments corresponding to the
expected inputs specified by your fulfillment.

Information about the conversation context, including the conversation ID, the type
(for example, whether this request is initiating a new conversation), and a conversation token
to store persistent data across the conversation lifespan.

Response body

The Content-Type in the header of HTTP posts from your fulfillment endpoint
to the Assistant must be application/json.

A response in the
conversation webhook format contains data such as the actual UI to show the
user (including audio and visual components), and the intent that can be
triggered in the subsequent request (called an expected intent). The expected
intent can be any of the intents that the Assistant understands, as described
in the Intents API reference.

Note: In your webhook responses, you'll typically specify actions.intent.TEXT
as the expected intent. This intent represents a raw text response from the
user. The generic ask() function in the client library expects this intent.

To learn more about formatting the user interface for your responses when
they're displayed in the Assistant, see the
Responses documentation.

Simple response example

The snippet below shows an example of a simple response in the conversation
webhook format.

Helper example

The snippet below shows an example of using a helper intent in the conversation
webhook format. In this example, the webhook is using the
actions.intent.OPTIONS helper intent to instruct the Assistant to obtain a
user selection between multiple options.

End conversation example

The snippet below shows an example of a simple response to end a conversation
session in the conversation webhook response format.

The expectedUserResponse
value of false in the response message signals to the Assistant that no further user
input is expected and that it should end the current conversation. The
finalResponse
value indicates what the Assistant should display or output to the user before
the conversation ends.