Fulfillment

Your app's fulfillment is hosted as an HTTP web service and defines the code for your app's functionality and for your conversation (the user interface for your app).

The conversation webhook defines the raw JSON request and response formats that the Google Assistant sends to your fulfillment and that your fulfillment responds back with. However, when you're developing, you'll want to use the Node.js client library to take advantage of developer conveniences.

Conversation Webhook

The conversation webhook defines how the Assistant sends you requests when users engage in a conversation with your app. Once a conversation occurs, it's identified by a conversationId. Every time the Assistant detects a user query, your fulfillment receives an intent that you process and respond to, and this conversationId is persisted in every request and response pair.

When users invoke an action in your app, the Assistant sends a request to your fulfillment. 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.

Your response contains data such as the actual UI to show the user (can contain both audio and visual components) and the intent that can be triggered in the subsequent response (called an expected intent). In general, this expected intent can be any of the intents that you can request for fulfillment for as described in the intents documentation.

See the Responses documentation for more information on how to format the UI for your responses when they're displayed in the Assistant.

Request Format

Requests from the Google Assistant occur when users invoke your app and interact with your actions. The request payload is formatted in JSON and is defined by conversation webhook request. Here's an example of a request:

{
    "user": {
        "userId": "wCBxFjVLK8I+nxIXfFOHEf/iAvvaTFuzUdBw6Gv5K3Q="
    },
    "conversation": {
        "conversationId": "1494709404186",
        "type": "NEW"
    },
    "inputs": [
        {
            "intent": "actions.intent.MAIN",
            "rawInputs": [
                {
                    "inputType": "KEYBOARD",
                    "query": "talk to my test app"
                }
            ]
        }
    ],
    "surface": {
        "capabilities": [
            {
                "name": "actions.capability.AUDIO_OUTPUT"
            },
            {
                "name": "actions.capability.SCREEN_OUTPUT"
            }
        ]
    }
}

Response Format

When you receive a request, your fulfillment must return a response that's defined by the conversation webhook response. Here's a sample JSON response and the corresponding Node.js client library code that responds to the request in the previous example.

JSON
{
    "conversationToken": "{\"state\":null,\"data\":{}}",
    "expectUserResponse": true,
    "expectedInputs": [
        {
            "inputPrompt": {
                "richInitialPrompt": {
                    "items": [
                        {
                            "simpleResponse": {
                                "textToSpeech": "Howdy! I can tell you fun facts about almost any number, like 42. What do you have in mind?",
                                "displayText": "Howdy! I can tell you fun facts about almost any number. What do you have in mind?"
                            }
                        }
                    ],
                    "suggestions": []
                }
            },
            "possibleIntents": [
                {
                    "intent": "actions.intent.TEXT"
                }
            ]
        }
    ]
}
Node.js
function simpleResponse (app) {
  app.ask({speech: 'Howdy! I can tell you fun facts about ' +
            'almost any number, like 42. What do you have in mind?',
            displayText: 'Howdy! I can tell you fun facts about almost any ' +
                  'number. What do you have in mind?'})
}