# Dialogflow webhook format {:#dialogflow-webhook-format} (Dialogflow)

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

If you are using Dialogflow to create Actions, your fulfillment
communicates with Dialogflow through its own, standard webhook format instead of the
Actions on Google conversation webhook format. The Dialogflow webhook format contains
all the information of the
[conversation webhook format](https://developers.google.com/assistant/df-asdk/reference/conversation-webhook-json)
along with additional Dialogflow-specific data, such as information about
contexts and parameters.

To see more examples of JSON messages for Dialogflow webhooks, you can refer
to this [GitHub project](https://github.com/dialogflow/fulfillment-webhook-json).

> [!NOTE]
> **Note:** For Dialogflow agents using V2 of the API with [beta features enabled](https://cloud.google.com/dialogflow-enterprise/docs/agents-versions), the values for the `session` and `outputContexts.name` attributes will start with `projects/${PROJECTID}/agent/environments/${ENVID}/users/${USERID}/sessions/${SESSIONID}`. (In Dialogflow V2 without beta feature enabled, this starts with `projects/${PROJECTID}/agent/sessions/${SESSIONID}`.)

## Request body

The [request](https://dialogflow.com/docs/fulfillment#request) message from
Dialogflow contains data in the Dialogflow webhook format. This object includes
Actions on Google-specific information, as summarized below:

- The `originalDetectIntentRequest.source` value is "google".
- The `originalDetectIntentRequest.version` indicates the Actions on Google version for the request.
- The `originalDetectIntentRequest.payload` contains key Actions on Google-specific information, including the conversation [request](https://developers.google.com/assistant/conversational/reference/rest/Shared.Types/AppRequest) JSON from the Assistant.
- The `Conversation.conversationToken` field is not supported by Dialogflow webhook requests. Instead, your fulfillment can use a Dialogflow [context](https://dialogflow.com/docs/examples/contexts) to persist data across the conversation lifespan.

### Simple invocation request example

The snippet below shows an example of an invocation request in the Dialogflow
webhook format.

    {
      "responseId": "c4b863dd-aafe-41ad-a115-91736b665cb9",
      "queryResult": {
        "queryText": "GOOGLE_ASSISTANT_WELCOME",
        "action": "input.welcome",
        "parameters": {},
        "allRequiredParamsPresent": true,
        "fulfillmentText": "",
        "fulfillmentMessages": [],
        "outputContexts": [
          {
            "name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/google_assistant_welcome"
          },
          {
            "name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/actions_capability_screen_output"
          },
          {
            "name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/google_assistant_input_type_voice"
          },
          {
            "name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/actions_capability_audio_output"
          },
          {
            "name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/actions_capability_web_browser"
          },
          {
            "name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/actions_capability_media_response_audio"
          }
        ],
        "intent": {
          "name": "projects/${PROJECTID}/agent/intents/8b006880-0af7-4ec9-a4c3-1cc503ea8260",
          "displayName": "Default Welcome Intent"
        },
        "intentDetectionConfidence": 1,
        "diagnosticInfo": {},
        "languageCode": "en-us"
      },
      "originalDetectIntentRequest": {
        "source": "google",
        "version": "2",
        "payload": {
          "isInSandbox": true,
          "surface": {
            "capabilities": [
              {
                "name": "actions.capability.SCREEN_OUTPUT"
              },
              {
                "name": "actions.capability.AUDIO_OUTPUT"
              },
              {
                "name": "actions.capability.WEB_BROWSER"
              },
              {
                "name": "actions.capability.MEDIA_RESPONSE_AUDIO"
              }
            ]
          },
          "inputs": [
            {
              "rawInputs": [
                {
                  "query": "Talk to my test app",
                  "inputType": "VOICE"
                }
              ],
              "intent": "actions.intent.MAIN"
            }
          ],
          "user": {
            "lastSeen": "2018-03-16T22:08:48Z",
            "permissions": [
              "UPDATE"
            ],
            "locale": "en-US",
            "userId": "ABwppHEvwoXs18xBNzumk18p5h02bhRDp_riW0kTZKYdxB6-LfP3BJRjgPjHf1xqy1lxqS2uL8Z36gT6JLXSrSCZ"
          },
          "conversation": {
            "conversationId": "${SESSIONID}",
            "type": "NEW"
          },
          "availableSurfaces": [
            {
              "capabilities": [
                {
                  "name": "actions.capability.SCREEN_OUTPUT"
                },
                {
                  "name": "actions.capability.AUDIO_OUTPUT"
                }
              ]
            }
          ]
        }
      },
      "session": "projects/${PROJECTID}/agent/sessions/${SESSIONID}"
    }

### Simple conversation request example

The snippet below shows an example of a conversational request in the Dialogflow
webhook format, where the user input is a text string.

    {
      "responseId": "68efa569-4ba1-4b7f-9b1b-ac2865deb539",
      "queryResult": {
        "queryText": "query from the user",
        "action": "action.name.of.matched.dialogflow.intent",
        "parameters": {},
        "allRequiredParamsPresent": true,
        "outputContexts": [
          {
            "name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/actions_capability_screen_output"
          },
          {
            "name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/actions_capability_audio_output"
          },
          {
            "name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/google_assistant_input_type_keyboard"
          },
          {
            "name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/actions_capability_media_response_audio"
          },
          {
            "name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/actions_capability_web_browser"
          }
        ],
        "intent": {
          "name": "projects/${PROJECTID}/agent/intents/1f4e5bd9-a670-4161-a22e-2c97b077f29f",
          "displayName": "Name of Dialogflow Intent"
        },
        "intentDetectionConfidence": 1,
        "diagnosticInfo": {},
        "languageCode": "en-us"
      },
      "originalDetectIntentRequest": {
        "source": "google",
        "version": "2",
        "payload": {
          "isInSandbox": true,
          "surface": {
            "capabilities": [
              {
                "name": "actions.capability.SCREEN_OUTPUT"
              },
              {
                "name": "actions.capability.AUDIO_OUTPUT"
              },
              {
                "name": "actions.capability.WEB_BROWSER"
              },
              {
                "name": "actions.capability.MEDIA_RESPONSE_AUDIO"
              }
            ]
          },
          "inputs": [
            {
              "rawInputs": [
                {
                  "query": "query from the user",
                  "inputType": "KEYBOARD"
                }
              ],
              "arguments": [
                {
                  "rawText": "query from the user",
                  "textValue": "query from the user",
                  "name": "text"
                }
              ],
              "intent": "actions.intent.TEXT"
            }
          ],
          "user": {
            "lastSeen": "2017-10-06T01:06:56Z",
            "locale": "en-US",
            "userId": "AI_yXq-AtrRh3mJX5D-G0MsVhqun"
          },
          "conversation": {
            "conversationId": "1522951193000",
            "type": "ACTIVE",
            "conversationToken": "[]"
          },
          "availableSurfaces": [
            {
              "capabilities": [
                {
                  "name": "actions.capability.SCREEN_OUTPUT"
                },
                {
                  "name": "actions.capability.AUDIO_OUTPUT"
                }
              ]
            }
          ]
        }
      },
      "session": "projects/${PROJECTID}/agent/sessions/${SESSIONID}"
    }

### Helper result example

The snippet below shows an example of a helper result in the Dialogflow webhook format.
This example shows the user's response after the webhook indicates to the Assistant
that it needs to obtain the user's confirmation.

    {
      "responseId": "cb6f5ec2-c26e-4349-b561-a9ddd6a0e495",
      "queryResult": {
        "queryText": "actions_intent_CONFIRMATION",
        "action": "Dialogflow action name of matched intent",
        "parameters": {},
        "allRequiredParamsPresent": true,
        "outputContexts": [
          {
            "name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/actions_intent_confirmation",
            "parameters": {
              "CONFIRMATION": true
            }
          }
        ],
        "intent": {
          "name": "projects/${PROJECTID}/agent/intents/1777d616-a5f7-4838-a9a9-870f2956bd14",
          "displayName": "Dialogflow action name of matched intent"
        },
        "intentDetectionConfidence": 1,
        "diagnosticInfo": {},
        "languageCode": "en-us"
      },
      "originalDetectIntentRequest": {
        "source": "google",
        "version": "2",
        "payload": {
          "isInSandbox": true,
          "surface": {},
          "inputs": [
            {
              "rawInputs": [
                {
                  "query": "yes",
                  "inputType": "VOICE"
                }
              ],
              "arguments": [
                {
                  "name": "CONFIRMATION",
                  "boolValue": true
                }
              ],
              "intent": "actions.intent.CONFIRMATION"
            }
          ],
          "user": {},
          "conversation": {},
          "availableSurfaces": []
        }
      },
      "session": "projects/${PROJECTID}/agent/sessions/${SESSIONID}"
    }

## Response body

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

The response message that your fulfillment sends to Dialogflow must be in
the [Dialogflow webhook format](https://dialogflow.com/docs/fulfillment#response).

When communicating with the Assistant, your response typically contains a `payload`
object that encapsulates a "`google`" object. The "`google`" payload object includes
Actions on Google-specific information. It must contain, at minimum, an
`expectUserResponse` field, and either a `richResponse` or `systemIntent` field.

The key fields for the "`google`" payload object are summarized below:

| Field | Description |
|---|---|
| `https://developers.google.com/assistant/conversational/reference/rest/Shared.Types/AppResponse#FIELDS.expect_user_response` | Indicates whether your fulfillment expects a user response. Set the value to `true` when to keep the conversation going and `false` to end the conversation. |
| `https://developers.google.com/assistant/conversational/reference/rest/Shared.Types/AppResponse#FIELDS.user_storage` | Stores persistent data tied to a specific user. The total storage amount is 10,000 bytes. |
| `https://developers.google.com/assistant/conversational/reference/rest/Shared.Types/AppResponse#richresponse` | This field contains audio, text, cards, suggestions, or structured data for the Assistant to render. To learn more about using rich responses for Actions on Google, see [Rich responses](https://developers.google.com/assistant/df-asdk/rich-responses) |
| `systemIntent` | This field has the same structure as `https://developers.google.com/assistant/conversational/reference/rest/Shared.Types/AppResponse#ExpectedInput.FIELDS.possible_intents`. Your response typically contains a `systemIntent` if your fulfillment is using a [helper intent](https://developers.google.com/assistant/df-asdk/helpers). The `https://developers.google.com/assistant/conversational/reference/rest/Shared.Types/AppResponse#ExpectedInput.FIELDS.possible_intents` field in the `systemIntent` must be set to an `https://developers.google.com/assistant/conversational/reference/rest/Shared.Types/AppResponse#ExpectedIntent` object, with the `inputValueData` field name changed to `data`. |

Within the [`ExpectedIntent`](https://developers.google.com/assistant/conversational/reference/rest/Shared.Types/AppResponse#ExpectedIntent)
object, you specify these values:

- **intent**: An intent name for the helper that indicates the type of information you want the user to provide, and
- **data**: A value specification, which is a string that describes the data that's required for the Assistant to carry out the helper.

For example, if you are asking for the user's permission, set the `intent` to
`actions.intent.PERMISSSION` and the `data` to the value specification to
`"@type": "type.googleapis.com/google.actions.v2.PermissionValueSpec"`, along with the fields for
that type.

The following list summarizes the value specification strings for helpers that you can set in a
`systemIntent` for a Dialogflow webhook response. For a full list of the Actions on Google intents
for conversational control, see the
[Intents](https://developers.google.com/assistant/df-asdk/reference/intents) reference.

| Intent Name | Dialogflow Event Name | Value Specification | Description |
|---|---|---|---|
| `https://developers.google.com/assistant/df-asdk/helpers#confirmation` | `actions_intent_CONFIRMATION` | `"@type": "type.googleapis.com/google.actions.v2.ConfirmationValueSpec"` | Obtains a confirmation from the user (for example, an answer to a yes or no question). |
| `https://developers.google.com/assistant/df-asdk/helpers#date_and_time` | `actions_intent_DATETIME` | `"@type": "type.googleapis.com/google.actions.v2.DateTimeValueSpec"` | Obtains a date and time input from the user. |
| `actions.intent.DELIVERY_ADDRESS` | `actions_intent_DELIVERY_ADDRESS` | `"@type": "type.googleapis.com/google.actions.v2.DeliveryAddressValueSpec"` | Obtains a delivery address input from the user. |
| `https://developers.google.com/assistant/df-asdk/helpers#android_link` | `actions_intent_LINK` | `"@type": "type.googleapis.com/google.actions.v2.LinkValueSpec"` | Requests a deep link flow into an Android app. |
| `https://developers.google.com/assistant/df-asdk/helpers#list_and_carousel_option` | `actions_intent_OPTION` | `"@type": "type.googleapis.com/google.actions.v2.OptionValueSpec"` | Obtains the selected item from a list or carousel UI. |
| `https://developers.google.com/assistant/df-asdk/helpers#user_information` | `actions_intent_PERMISSION` | `"@type": "type.googleapis.com/google.actions.v2.PermissionValueSpec"` | Obtains the user's information including full name, coarse location, or precise location. |
| `https://developers.google.com/assistant/df-asdk/helpers#account_sign-in` | `actions_intent_SIGN_IN` | `"@type": "type.googleapis.com/google.actions.v2.SignInValueSpec"` | Requests an account linking flow to link a user's account. |

### Simple response example

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

    {
      "payload": {
        "google": {
          "expectUserResponse": true,
          "richResponse": {
            "items": [
              {
                "simpleResponse": {
                  "textToSpeech": "this is a simple response"
                }
              }
            ]
          }
        }
      }
    }

### Helper example

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

    {
      "payload": {
        "google": {
          "expectUserResponse": true,
          "richResponse": {
            "items": [
              {
                "simpleResponse": {
                  "textToSpeech": "Choose a item"
                }
              }
            ]
          },
          "systemIntent": {
            "intent": "actions.intent.OPTION",
            "data": {
              "@type": "type.googleapis.com/google.actions.v2.OptionValueSpec",
              "listSelect": {
                "title": "Hello",
                "items": [
                  {
                    "optionInfo": {
                      "key": "first title key"
                    },
                    "description": "first description",
                    "image": {
                      "url": "/assistant/images/badges/XPM_BADGING_GoogleAssistant_VER.png",
                      "accessibilityText": "first alt"
                    },
                    "title": "first title"
                  },
                  {
                    "optionInfo": {
                      "key": "second"
                    },
                    "description": "second description",
                    "image": {
                      "url": "https://lh3.googleusercontent.com/Nu3a6F80WfixUqf_ec_vgXy_c0-0r4VLJRXjVFF_X_CIilEu8B9fT35qyTEj_PEsKw",
                      "accessibilityText": "second alt"
                    },
                    "title": "second title"
                  }
                ]
              }
            }
          }
        }
      }
    }

On receiving the message from the previous example, the Assistant temporarily
takes over the conversation and prompts the user to make a selection based on
the given options. On collecting all the required user input, the Assistant
sends this helper result back to your fulfillment in a Dialogflow webhook request.

The snippet below shows an example of the helper result with the user choice selection.

    {
      "responseId": "ea166558-615a-48f3-ae5b-7f55d895784b",
      "queryResult": {
        "queryText": "actions_intent_OPTION",
        "action": "",
        "parameters": {},
        "allRequiredParamsPresent": true,
        "fulfillmentText": "",
        "fulfillmentMessages": [],
        "outputContexts": [
          {
            "name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/actions_intent_option",
            "parameters": {
              "OPTION": "key of selected item"
            }
          }
        ],
        "intent": {
          "name": "projects/${PROJECTID}/agent/intents/1777d616-a5f7-4838-a9a9-870f2956bd14",
          "displayName": "Dialogflow intent name of matched intent"
        },
        "intentDetectionConfidence": 1,
        "diagnosticInfo": {},
        "languageCode": "en-us"
      },
      "originalDetectIntentRequest": {
        "source": "google",
        "version": "2",
        "payload": {
          "isInSandbox": true,
          "surface": {
            "capabilities": []
          },
          "inputs": [
            {
              "rawInputs": [
                {
                  "query": "Title of selected item",
                  "inputType": "TOUCH"
                }
              ],
              "arguments": [
                {
                  "textValue": "Key of selected item",
                  "name": "OPTION"
                }
              ],
              "intent": "actions.intent.OPTION"
            }
          ],
          "user": {},
          "conversation": {},
          "availableSurfaces": []
        }
      },
      "session": "projects/${PROJECTID}/agent/sessions/${SESSIONID}"
    }

### End conversation example

The snippet below shows an example of a simple response to end a conversation
session in the Dialogflow webhook format. The
[`expectUserResponse`](https://developers.google.com/assistant/conversational/reference/rest/Shared.Types/AppResponse#FIELDS.expect_user_response)
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.

    {
      "payload": {
        "google": {
          "expectUserResponse": false,
          "richResponse": {
            "items": [
              {
                "simpleResponse": {
                  "textToSpeech": "Goodbye!"
                }
              }
            ]
          }
        }
      }
    }

To learn how to override the default behavior when users invoke a standard
phrase to end a conversation with the Assistant, see the
[conversation exits guide](https://developers.google.com/assistant/df-asdk/conversation-exits).