# Conversation webhook format {:#conversation-webhook-format} (Dialogflow)

This section describes the format of the JSON payload when Actions on Google invokes your
fulfillment through the [Actions SDK](https://developers.google.com/assistant/df-asdk/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](https://developers.google.com/assistant/df-asdk/reference/intents) that
your webhook must process and respond to. This `conversationId`is persisted in every request and
response pair until the conversation ends.

> [!NOTE]
> **Note:** Your response must occur within 10 seconds, otherwise the Assistant assumes your fulfillment has timed out and ends your conversation.

## Request body

When users make an initial query or provide some subsequent input, the Assistant sends a request
to your fulfillment. [Conversation webhook requests](https://developers.google.com/assistant/df-asdk/reference/webhook/rest/Shared.Types/AppRequest)
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:

| Field | Description |
|---|---|
| `https://developers.google.com/assistant/df-asdk/reference/webhook/rest/Shared.Types/AppRequest#FIELDS.is_in_sandbox` | This boolean variable is primarily used to for the [transactions](https://developers.google.com/assistant/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`". |
| `https://developers.google.com/assistant/df-asdk/reference/webhook/rest/Shared.Types/AppRequest#surface` | Information about the Assistant surface the user is interacting with and its capabilities. |
| `https://developers.google.com/assistant/df-asdk/reference/webhook/rest/Shared.Types/AppRequest#inputs` | Information about the invocation request. For the triggering invocation, this includes an [intent](https://developers.google.com/assistant/df-asdk/reference/intents) 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. |
| `https://developers.google.com/assistant/df-asdk/reference/webhook/rest/Shared.Types/AppRequest#user)` | Information about the user who initiated the request. This information includes permissions granted by the user, and the user's locale. |
| `https://developers.google.com/assistant/df-asdk/reference/webhook/rest/Shared.Types/AppRequest#conversation` | 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. |
| `availableSurfaces` | This information is used for [multi-surface conversations](https://developers.google.com/assistant/df-asdk/surface-capabilities#multi-surface_conversations). |

### Simple invocation request example

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

```
{
  "user": {
    "userId": "ABwppHEF...",
    "locale": "en-US",
    "lastSeen": "2018-03-21T17:59:52Z",
    "userStorage": "{\"data\":{}}"
  },
  "device": {},
  "surface": {
    "capabilities": [
      {
        "name": "actions.capability.SCREEN_OUTPUT"
      },
      {
        "name": "actions.capability.AUDIO_OUTPUT"
      },
      {
        "name": "actions.capability.MEDIA_RESPONSE_AUDIO"
      },
      {
        "name": "actions.capability.WEB_BROWSER"
      }
    ]
  },
  "conversation": {
    "conversationId": "1521784527171",
    "type": "NEW"
  },
  "inputs": [
    {
      "intent": "actions.intent.MAIN",
      "rawInputs": [
        {
          "inputType": "VOICE",
          "query": "Talk to my test app"
        }
      ]
    }
  ],
  "availableSurfaces": [
    {
      "capabilities": [
        {
          "name": "actions.capability.SCREEN_OUTPUT"
        },
        {
          "name": "actions.capability.AUDIO_OUTPUT"
        },
        {
          "name": "actions.capability.MEDIA_RESPONSE_AUDIO"
        },
        {
          "name": "actions.capability.WEB_BROWSER"
        }
      ]
    }
  ]
}
```

### Simple conversation request example

The snippet below shows an example of a conversational request in the conversation webhook format,
where the user input is a text string (for example, *"My lucky number is 88."*):

```
{
  "user": {
    "userId": "ABwppHEF...",
    "locale": "en-US",
    "lastSeen": "2018-03-21T17:59:52Z",
    "userStorage": "{\"data\":{}}"
  },
  "device": {},
  "surface": {
    "capabilities": [
      {
        "name": "actions.capability.SCREEN_OUTPUT"
      },
      {
        "name": "actions.capability.AUDIO_OUTPUT"
      },
      {
        "name": "actions.capability.MEDIA_RESPONSE_AUDIO"
      },
      {
        "name": "actions.capability.WEB_BROWSER"
      }
    ]
  },
  "conversation": {
    "conversationId": "1521784527171",
    "type": "NEW"
  },
  "inputs": [
    {
      "intent": "actions.intent.TEXT",
      "rawInputs": [
        {
          "inputType": "VOICE",
          "query": "My lucky number is 88."
        }
      ]
    }
  ],
  "availableSurfaces": [
    {
      "capabilities": [
        {
          "name": "actions.capability.SCREEN_OUTPUT"
        },
        {
          "name": "actions.capability.AUDIO_OUTPUT"
        },
        {
          "name": "actions.capability.MEDIA_RESPONSE_AUDIO"
        },
        {
          "name": "actions.capability.WEB_BROWSER"
        }
      ]
    }
  ]
}
```

## Response body

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

A [response](https://developers.google.com/assistant/df-asdk/reference/webhook/rest/Shared.Types/AppResponse) 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](https://developers.google.com/assistant/df-asdk/reference/intents) API reference.

> [!NOTE]
> **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](https://developers.google.com/assistant/df-asdk/responses) documentation.

### Simple response example

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

```
{
  "expectUserResponse": true,
  "expectedInputs": [
    {
      "possibleIntents": [
        {
          "intent": "actions.intent.TEXT"
        }
      ],
      "inputPrompt": {
        "richInitialPrompt": {
          "items": [
            {
              "simpleResponse": {
                "textToSpeech": "You are using the Actions SDK. Do you want to hear more about it?"
              }
            }
          ]
        }
      }
    }
  ]
}
```

### 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.

To learn more about using helper intents, see the
[Helpers](https://developers.google.com/assistant/df-asdk/helpers) guide.

```
{
  "expectUserResponse": true,
  "expectedInputs": [
    {
      "possibleIntents": [
        {
          "intent": "actions.intent.OPTION",
          "inputValueData": {
            "@type": "type.googleapis.com/google.actions.v2.OptionValueSpec",
            "carouselSelect": {
              "items": [
                {
                  "optionInfo": {
                    "key": "one",
                    "synonyms": [
                      "synonym of KEY_ONE 1",
                      "synonym of KEY_ONE 2"
                    ]
                  },
                  "description": "Description of number one",
                  "title": "Number one"
                },
                {
                  "optionInfo": {
                    "key": "two",
                    "synonyms": [
                      "synonym of KEY_TWO 1",
                      "synonym of KEY_TWO 2"
                    ]
                  },
                  "description": "Description of number two",
                  "title": "Number two"
                }
              ]
            }
          }
        }
      ],
      "inputPrompt": {
        "richInitialPrompt": {
          "items": [
            {
              "simpleResponse": {
                "textToSpeech": "this shows an example of a carousel"
              }
            }
          ],
          "suggestions": [
            {
              "title": "1"
            },
            {
              "title": "2"
            }
          ]
        }
      }
    }
  ]
}
```

### 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`](https://developers.google.com/assistant/df-asdk/reference/webhook/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. The
[`finalResponse`](https://developers.google.com/assistant/df-asdk/reference/webhook/rest/Shared.Types/AppResponse#FinalResponse)
value indicates what the Assistant should display or output to the user before
the conversation ends.

```
{
  "expectUserResponse": false,
  "finalResponse": {
    "richResponse": {
      "items": [
        {
          "simpleResponse": {
            "textToSpeech": "Good bye"
          }
        }
      ]
    }
  }
}
```

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