How fulfillment works

You can enable fulfillment for any of your agent's intents. To use fulfillment, you need to set up a webhook. A webhook is a web server endpoint that you create and host.

Webhook request

When an intent with fulfillment enabled is matched, Dialogflow will make an HTTP POST request to your webhook with a JSON object containing information about the matched intent.

After receiving a request, the webhook can perform any required tasks. For example, the webhook might use information from the request to look up a product in a database or place an order.

Finally, your webhook should respond back with instructions for what Dialogflow should do next.

Request format

The request to your webhook will have the following fields:

V2 API

Name Type Description
responseId String Unique id for request.
session String Unique session id.
queryResult Object Result of the conversation query or event processing.
queryText String The original text of the query.
parameters Object Consists of parameter_name:parameter_value pairs.
allRequiredParamsPresent Boolean Set to false if required parameters are missing in query.
fulfillmentText String Text to be pronounced to the user or shown on the screen.
fulfillmentMessages Object Collection of rich messages to show the user.
outputContexts Object Collection of output contexts.
intent Object The intent that matched the user's query.
intentDetectionConfidence Number 0-1 Matching score for the intent.
diagnosticInfo Object Free-form diagnostic info.
languageCode String The language that was triggered during intent matching.
originalDetectIntentRequest Object Full request coming from an integrated platform. (Facebook Messenger, Slack, etc.)

V1 API

Name Type Description
originalRequest Object Full request coming from an integrated platform. (Facebook Messenger, Slack, etc.)
id String Unique id of request.
sessionId String Unique session id.
timestamp String Date and time of the request in UTC timezone using ISO-8601 format.
timezone String Time zone from IANA Time Zone Database.
lang String Language of request.
result Object Related information resulting from request.
source String Request source name. (google, facebook, slack, etc.)
resolvedQuery String The query that was used to produce the result.
speech String Text to be pronounced to the user / shown on the screen.
action String Matched Dialogflow intent action name.
actionIncomplete Boolean Whether or not all required parameters were collected.
parameters Object Consists of parameter_name:parameter_value pairs.
contexts Object Array of context objects.
↳- name String The name of the context.
↳- parameters Objects Parameters carried over via context.
↳- lifespan Number Number of requests after which the context will expire.
metadata Object Contains data about matched intent.
↳- intentId String Unique identifier for intent.
↳- webhookUsed Boolean Indicates if webhook is enabled in the matched intent.
↳- webhookForSlotFillingUsed Boolean Indicates if webhook is handling required parameters.
↳- nluResponseTime Number Time to complete request.
↳- intentName String Name of the matched intent.
fulfillment Object Contains data about responses, rich messages, responses from webhook.
↳- speech String Text to be pronounced to the user / shown on the screen.
↳- messages Object Array of message objects.
score Number 0-1 Matching score for the intent.

Sample request to the service

Here are sample requests to the service in V2 and V1 API formats:

V2 API

POST https://my-service.com/action

Headers:
//user defined headers
Content-type: application/json

POST body:
{
  "responseId": "ea3d77e8-ae27-41a4-9e1d-174bd461b68c",
  "session": "projects/your-agents-project-id/agent/sessions/88d13aa8-2999-4f71-b233-39cbf3a824a0",
  "queryResult": {
    "queryText": "user's original query to your agent",
    "parameters": {
      "param": "param value"
    },
    "allRequiredParamsPresent": true,
    "fulfillmentText": "Text defined in Dialogflow's console for the intent that was matched",
    "fulfillmentMessages": [
      {
        "text": {
          "text": [
            "Text defined in Dialogflow's console for the intent that was matched"
          ]
        }
      }
    ],
    "outputContexts": [
      {
        "name": "projects/your-agents-project-id/agent/sessions/88d13aa8-2999-4f71-b233-39cbf3a824a0/contexts/generic",
        "lifespanCount": 5,
        "parameters": {
          "param": "param value"
        }
      }
    ],
    "intent": {
      "name": "projects/your-agents-project-id/agent/intents/29bcd7f8-f717-4261-a8fd-2d3e451b8af8",
      "displayName": "Matched Intent Name"
    },
    "intentDetectionConfidence": 1,
    "diagnosticInfo": {},
    "languageCode": "en"
  },
  "originalDetectIntentRequest": {}
}

V1 API

POST https://my-service.com/action

Headers:
//user defined headers
Content-type: application/json

POST body:

{
  "originalRequest": {},
  "id": "7811ac58-5bd5-4e44-8d06-6cd8c67f5406",
  "sessionId": "1515191296300",
  "timestamp": "2018-01-05T22:35:05.903Z",
  "timezone": "",
  "lang": "en-us",
  "result": {
    "source": "agent",
    "resolvedQuery": "user's original query to your agent",
    "speech": "Text defined in Dialogflow's console for the intent that was matched",
    "action": "Matched Dialogflow intent action name",
    "actionIncomplete": false,
    "parameters": {
      "param": "param value"
    },
    "contexts": [
      {
        "name": "incoming context name",
        "parameters": {},
        "lifespan": 0
      }
    ],
    "metadata": {
      "intentId": "29bcd7f8-f717-4261-a8fd-2d3e451b8af8",
      "webhookUsed": "true",
      "webhookForSlotFillingUsed": "false",
      "nluResponseTime": 6,
      "intentName": "Name of Matched Dialogflow Intent"
    },
    "fulfillment": {
      "speech": "Text defined in Dialogflow's console for the intent that was matched",
      "messages": [
        {
          "type": 0,
          "speech": "Text defined in Dialogflow's console for the intent that was matched"
        }
      ]
    },
    "score": 1
  }
}

Webhook response

Once requested, your webhook should provide a response. In the response, you can specify the following things:

  • The response that Dialogflow returns to the user.
  • Updates to the contexts attached to the conversation.
  • A followup event name that would cause another intent to be invoked.
  • An arbitrary payload that can be sent to the original Dialogflow caller.

The response should occur within five seconds and be no larger than 64K in size.

Response format

The response from your webhook should have the following fields:

V2 API

Name Type Description
fulfillmentText String Optional. The text to be shown on the screen. This value is passed directly to QueryResult.fulfillment_text.
fulfillmentMessages[] Object (Message) Optional. The collection of rich messages to present to the user. This value is passed directly to QueryResult.fulfillment_messages.
source String Optional. This value is passed directly to QueryResult.webhook_source.
payload Object (Struct) Optional. This value is passed directly to QueryResult.webhook_payload.
outputContexts[] Object (Context) Optional. The collection of output contexts. This value is passed directly to QueryResult.output_contexts.
followupEventInput Object (EventInput) Optional. Makes the platform immediately invoke another sessions.detectIntent call internally with the specified event as input.

V1 API

Name Type Description
speech String Response to the request.
displayText String Text displayed on the user device screen.
data Object Additional data required for performing the action on the client side. The data is sent to the client in the original form and is not processed by Dialogflow.
contextOut Array of context objects Array of context objects set after intent completion.
source String Data source.
followupEvent Object Event name and optional parameters sent from the web service to Dialogflow. Read more

Sample response from the service:

V2 API

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

V1 API

{
"speech": "this text is spoken out loud if the platform supports voice interactions",
"displayText": "this text is displayed visually",
"messages": {
  "type": 1,
  "title": "card title",
  "subtitle": "card text",
  "imageUrl": "https://assistant.google.com/static/images/molecule/Molecule-Formation-stop.png"
},
"data": {
  "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."
  }
},
"contextOut": [
  {
    "name": "context name",
    "lifespan": 5,
    "parameters": {
      "param": "param value"
    }
  }
],
"source": "example.com",
"followupEvent": {
  "name": "event name",
  "parameters": {
    "param": "param value"
  }
}

}

Handle errors

If your webhook exceeds the five second timeout, is unavailable, or returns one of the following HTTP status codes indicating an error, Dialogflow responds to the user using whatever default response is defined in the intent's Responses section.

  • 400 Bad Request
  • 401 Unauthorized
  • 403 Forbidden
  • 404 Not found
  • 500 Server fault
  • 503 Service Unavailable

In addition, if Dialogflow was originally invoked via the detectIntent API, the status field in the response sent to the client will be as follows:

"status": {
    "code": 206,
    "errorType": "webhook call failed with %error Code% error"
}

In the above snippet, code is the error ID received from the service.