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.

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:

Field Description
isInSandbox 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".
surface Information about the Assistant surface the user is interacting with and its capabilities.
Inputs 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.
User Information about the user who initiated the request. This information includes permissions granted by the user, and the user's locale.
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.

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

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.

{
  "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 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 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.

{
  "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.