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.