Dialogue Fulfillment

Dialogue skills, if needed to visit one's own services for responses or if you need to integrate with other systems, fulfillment is the best option. Fulfillment allows for connections to other services and systems to send customized rich responses back to the end users.

Fulfillment can be enabled in any Intent. Fulfillment is disabled by default, in which case the skill returns normal template responses. When fulfillment is enabled, the skill will always send one's request (along with some other information) to the service (an external API or a Webhook) instead, when an intent is matched. For example, building a service to check the average gas price of a specific type (regular or premium) in a specific city. The service needs to first collect this information from intents and subsequently call a third-party service (gas price quote API), find out the price and send it back.

A brief processing flow for dialogue fulfillment is shown in the diagram below.

How To Use

First, create a new dialogue skill (either from within the bot or from “My skills”).

Next, enter the skill. Intents and Entities can be created as needed. In the example, an intent called “GasPriceQuote” and two entities “CanadianGasType” and “CanadianCities” can be created, as shown in the figures below.

Intent:

Entities:

In this example, fulfillment is disabled by default, in which case any queries matching the intent returns templated answer “109.9 cents/litre”, as shown in the figure below:

Fulfillment can be enabled from the “fulfillment” panel on the left. Slide the toggled to the right to turn this feature on. Fill in the fulfillment API service address.

When fulfillment is turned on, the old template answers will be automatically shadowed, as shown below.

When fulfillment is enabled, the platform will instead send a HTTP POST to one's service/webhook. This HTTP POST request contains information about the skill, the matched intent and all matched entities/slots in its request body.

In this case, there is an external service that takes the entities “CanadianGasType”, “CanadianCities”, and the original request as input. The HTTP POST request body sent to your service/webhook may look like below.

[
   {
      "skillid":"2c9480d26e61b5b3016ff385d3af17a4",
      "query":"How much is a litre of regular gas cost in Waterloo?",
      "intentid":"2c9480d26e61b5b3016ff3861fb617a5",
      "slotProperties":{
         "CanadianCities":[
            {
               "slotType":"CanadianCities",
               "value":"Waterloo",
               "key":"Waterloo"
            }
         ],
         "GasType":[
            {
               "slotType":"CanadianGasType",
               "value":"premium",
               "key":"premium"
            }
         ]
      }
   }
]

One's service/Webhook is expected to take actions based on these fields and return dynamic responses. In the example, one's service/webhook can visit some third-party gas price lookup API, find out the gas price, and return it to the end user. Customized items including images, video, cards and so on can be implemented.

An example output/callback from the service/webhook might look like below. For a complete set of response types (including images, videos, audios, cards, quick replies, etc) that are supported, please refer to Rich Response Documentation.

{
   "stage":[
      {
         "text":{
            "text":[
               "Average regular gas price in Waterloo is: 112.4 cents/litre "
            ]
         }
      },
      {
        "image": {
          "title": "Image Title",
          "url":   "http://www.example.org/Costco-Waterloo-Ontario-Gas-Station.jpg",
          "alt": "Some image."
        }
      }
  ]
}

Which will be rendered as a piece of text and an image, shown below.

Advanced Features

Error Handling

To indicate an error has occurred, add status, errorMsg and exception fields to outputs/callbacks.

An example is shown below.

{
   "status":"failed",
   "errorMsg":"java.lang.NullPointerException.",
   "errorMsgFull":"Exception in thread main java.lang.NullPointerException at Entity.<init>(Entity.java:24) at Main.<init>(Main.java:22) at Main.main(Main.java:18)"
}

Chatbot APIFulfillment and Context