How does fulfillment work?

Every intent has a built-in response handler that can return responses after the intent is matched. However, this feature only allows you to construct responses that are static or have minimal logic. Most times, you'll want to use fulfillment to process the intent first, and then return a more intelligent or useful response. Fulfillment is custom logic that you implement as a webhook, which services requests, processes them, and returns responses.

Let's see how this works with a simple agent:

  1. Your agent matches a user utterance to an intent.
  2. Your agent extracts parameters out of the user utterance and calls your fulfillment with a JSON payload that contains the parameters along with a host of other useful information about the intent. Here's what a typical JSON request might look like for a user wanting to know the weather:

    {
    "responseId": "3e9a2ec3-d79c-4a90-92dd-2375cc687029",
    "queryResult": {
      "queryText": "What's the weather in Mountain View tomorrow?",
      "action": "weather",
      "parameters": {
        "date-time": "2018-08-10T12:00:00-07:00",
        "address": {
          "city": "Mountain",
          "business-name": "View"
        },
        "unit": "",
        "date-period": ""
      },
      "allRequiredParamsPresent": true,
      "fulfillmentMessages": [
        {
          "text": {
            "text": [
              ""
            ]
          }
        }
      ],
      "outputContexts": [
        {
          "name": "projects/weatherv2-784f4/agent/sessions/9f57c69d-e4cd-5f01-8ed9-fb72ea043570/contexts/weather",
          "lifespanCount": 2,
          "parameters": {
            "date-time.original": "tomorrow?",
            "unit.original": "",
            "unit": "",
            "address": {
              "city": "Mountain",
              "city.original": "Mountain",
              "city.object": {},
              "business-name": "View",
              "business-name.original": "View",
              "business-name.object": {}
            },
            "date-time": "2018-08-10T12:00:00-07:00",
            "date-period.original": "",
            "date-period": "",
            "address.original": "Mountain View"
          }
        }
      ],
      "intent": {
        "name": "projects/weatherv2-784f4/agent/intents/f1b75ecb-a35f-4a26-88fb-5a8049b92b02",
        "displayName": "weather"
      },
      "intentDetectionConfidence": 0.91,
      "languageCode": "en"
    },
    "originalDetectIntentRequest": {
      "payload": {}
    },
    "session": "projects/weatherv2-784f4/agent/sessions/9f57c69d-e4cd-5f01-8ed9-fb72ea043570"
    }
    
  3. Your fulfillment processes any necessary information it needs to from the JSON, such as calling another REST API with the extracted parameters.

  4. Your fulfillment constructs a response and returns it back to Dialogflow to render to the user. This response can be simple text or a rich response, such as a card with an image. A typical response might look like this:

    {
    "fulfillmentText": "This is a text response",
    "fulfillmentMessages": [
      {
        "card": {
          "title": "card title",
          "subtitle": "card text",
          "imageUri": "https://assistant.google.com/static/images/molecule/Molecule-Formation-stop.png",
          "buttons": [
            {
              "text": "button text",
              "postback": "https://assistant.google.com/"
            }
          ]
        }
      }
    ],
    "source": "example.com",
    "payload": {
      "google": {
        "expectUserResponse": true,
        "richResponse": {
          "items": [
            {
              "simpleResponse": {
                "textToSpeech": "this is a simple response"
              }
            }
          ]
        }
      },
      "facebook": {
        "text": "Hello, Facebook!"
      },
      "slack": {
        "text": "This is a text response for Slack."
      }
    },
    "outputContexts": [
      {
        "name": "projects/${PROJECT_ID}/agent/sessions/${SESSION_ID}/contexts/context name",
        "lifespanCount": 5,
        "parameters": {
          "param": "param value"
        }
      }
    ],
    "followupEventInput": {
      "name": "event name",
      "languageCode": "en-US",
      "parameters": {
        "param": "param value"
      }
    }
    }
    

Next steps

Now that you've learned how Dialogflow works and the basic principles of an agent, build your own with our getting started guide. The guide goes over how to use the Dialogflow console, how to create an agent and intents, and how to use the Dialogflow client library, so you don't have to parse JSON requests and construct JSON responses manually.