Reply Templates

Provide chatbot users with predefined lists of answers they can pick from.

NativeChat provides you a way to give users a list of predefined answers they can pick from. This helps them understand what they are being asked for and also limits the possibility of error when entering free text replies.

There are several different ways to display these predefined replies to the users.

{
  "steps": [
    {
      ...
      "message": "Here is what I can do for you:",
      ...
      "display": {
        "type": "quick-reply",
        ...
      }
      ...
    }    
  ]
}

The type property of the display object defines how to display the options. Supported values are:

  • quick-reply - displays the options as quick replies
  • location-picker - displays a prompt for location
  • date-picker - displays a calendar for picking a date
  • single-select - displays the options in a dialog window as a list of items. The items may contain not only text but images as well.
  • carousel - displays the options in a carousel view inside the chat.

quick-reply

Quick replies are shown as buttons in the chat UI after the step’s message. When the user clicks on a button, the text of the button is passed to the bot as if the user has typed it in the message box.

Here is an example:

Only 5 quick replies can be shown at a time. If the list of quick replies you defined in the Cognitive flow is with more than 5, NativeChat will show the system button “Next 5” / “Prev 5” that will show additional / previous 5 replies to the user. It works as a pagination in standard UIs. You can change the label of the system buttons in the Settings part of the Cognitive Flow.

You can define the list of quick replies shown to the users by one of the following ways.

From static array of quick replies

{
  "steps": [
    {
      "message": "Here is what I can do for you:",
      "display": {
        "type": "quick-reply",
        "data": [
          "Book a doctor",
          "Contact operator",
          "Restart"
        ]
      }
    }    
  ]
}
Name Type Required Description
data array No Default: none
An array of strings. Each string is displayed as a quick reply button in the chat.

From the values of custom entities

If you are asking about a custom entity (for example, Doctor) the quick replies can be inferred from the training data of that entity.

For example, if you have a Doctors custom entity type with these values:

Example training data for Doctor custom entity.

you can use this Cognitive flow definition

{
  "steps": [
    {
      "type": "question",
      "entity": "selectedDoctor",
      "entity-type": "Doctors",
      "message": "What's the name of the doctor that you want to see?",
      "display": {
        "type": "quick-reply"
      }
    }    
  ]
}

that will render these quick replies:

Location picker

From a webhook response

You can request the values of quick replies from external service.

For example, if you have API endpoint that returns an array of Doctor objects (each doctor has FirstName, LastName, Title etc.), you can define the following question step and quick reply display.

{
  "steps": [
    {
      "type": "question",
      "entity": "selectedDoctor",
      "entity-type": "Doctor",
      "messages": [
        "What's the name of the doctor that you want to see?"
      ],
      "display": {
        "type": "quick-reply",
        "data-source": {
          "endpoint": "https://yourwebsite.com/GetDoctors",
          "method": "GET",
          "selector": "$.Result[:]"
        },
        "template": "{{Title}} {{FirstName}} {{LastName}}"
      }
    }
  ]
}

Check the description of data-source for more information.

From the values of an entity stored in Bot Memory

You can use an custom entity that is already defined in the context as a data source. If the entity is not an array of strings, you can use the selector and template (see dynamic data-source) properties to construct the list of options that will be displayed to the user.

location-picker

Displays a prompt for the user to pick a location.

Location picker

{
  "steps": [
    {
      ...
      "display": {
        "type": "location-picker",
        "title": "Pick a location",
        "button-text": "Submit"
      }
    }    
  ]
}
Name Type Required Description
title string Yes Default: “Open”
Тhe name of the button shown in the chat.
button-text string No Default: “Submit”
Тhe name of the submit button in the Location picker dialog.

date-picker (web only)

Displays a date picker for the user to pick a date.

Date picker

{
  "steps": [
    {
      ...
      "display": {
        "type": "date-picker",
        "title": "Pick a date",
        "button-text": "Submit"
      }
    }
}
Name Type Required Description
title string Yes Default: “Open”
Тhe name of the button shown in the chat.
button-text string No Default: “Submit”
Тhe name of the submit button in the Date picker dialog.

single-select

Displays a list of options to the user where they can pick only one of these. Single select UI is presented in a dialog window. It is suitable for longer list (e.g. Countries, Cities, etc.) where other quick reply types won’t be that efficient.

Single-Select Webview

{
  "steps": [
    {
      ...
      "display": {
        "type": "single-select",
        "data-source": {
          "endpoint": "https://yourwebsite.com/GetDoctors",
          "method": "GET"
        },
        "title": "Choose a doctor",
        "button-text": "Submit",
        "template": {
          "title": "{{FirstName}} {{LastName}}",
          "subtitle": "{{Specialty}}",
          "image": "{{Image}}"
        }
      }
    }    
  ]
}
Name Type Required Description
type string No single-select
data array No Default: none
Static data for the options in the list. Learn more
data-source object No Default: none
Populate data for the list from external REST API. Learn more
title string Yes Default: none
Тhe text of the button shown in the chat that opens the single select dialog window.
button-text string No Default: “Submit”
Тhe text of the submit button in the dialog window.
template object No Default: none
Template for formatting the list options.

The template object has these properties:

Name Type Required Description
title string No* Default: if the array is composed of strings, the value of the string is displayed directly as the the option text.
The text in the list for each option.
subtitle string No Default: none
Second line of text for each option.
image string No Default: none
URL of an image file.
value string No Default: same as the value of the title property.
If you want to pass a value to the bot that is different from one shown as the title of the selected option.

Understanding title vs value.

It is important to understand that the value returned from the selection must be matched to the items defined in the Entity (in the training tab). So, if you change the title to be:

"title": "Office in "

Then selecting Office in Berlin will fail, as the City Entity doesn’t contain such record.

In this case, you need to use the value, which should provide the property that the chatbot could match to, like this:

"template": {
  "title": "Office in ",
  "subtitle": "",
  "value": ""
}

Displays the options in a carousel view inside the chat.

Carousel view

{
  "steps": [
    {
      ...
      "display": {
        "type": "carousel",
        "data-source": {
          "endpoint": "https://yourwebsite.com/GetInsurances",
          "method": "GET"
        },
        "title": "Pick an insurance plan",
        "button-text": "Select",
        "template": {
          "title": "{{Name}}",
          "subtitle": "{{$currency Price 'USD'}}",
          "image": "{{Image}}"
        },
      }
    }    
  ]
}
Name Type Required Description
button-text string No Default: “Select”
Тhe text of the button of each card that is used for selection.
template object Yes Define the content shown in a single carousel item.
title string Yes Required fallback for Viber. In Viber there is no carousel UI support and thus the NativeChat carousel is displayed as single-select. Title is the text of the button that opens a picker with the carousel options in a browser window.

The template object has these properties:

Name Type Required Description
title string Yes Default: none
The title text of a card in the carousel.
subtitle string No Default: none
The text shown under the title of the carousel item.
image string Yes Default: none
The URL of a image for that carousel item.

data (optional)

Provides a static list of options to show the user.

{
  "steps": [
    {
      "type": "question",
      "entity": "selectedDoctor",
      "entity-type": "Doctor",
      "messages": [
        "What's the name of the doctor that you want to see?"
      ],
      "display": {
        "type": "quick-reply",
        "data": [
          "Dr. John Burke",
          "Dr. Stan Smith",
          "Dr. Ivo Karlovic"
        ]
      }
    }
  ]
}

data-source (optional)

You can retrieve data from a web service or use an existing entity from the context to provide a list of options to the user.

dynamic

The result from the web service should always be an array. You can also set the template property to format the options. See “data-source” for configuration.

{
  "steps": [
    {
      "type": "question",
      "entity": "selectedDoctor",
      "entity-type": "Doctor",
      "messages": [
        "What's the name of the doctor that you want to see?"
      ],
      "display": {
        "type": "quick-reply",
        "data-source": {
          "endpoint": "https://yourwebsite.com/GetDoctors",
          "method": "GET",
          "selector": "$.Result[:]"
        },
        "template": "{{Title}} {{FirstName}} {{LastName}}"
      }
    }
  ]
}
Name Type Required Description
endpoint string Yes Default: none
The URL of your API endpoint.
method string Yes Default: none
The request method.
headers object No Default: none
The request headers.
payload object No Default: none
The request body.
selector object No Default: none
JSONPath expression to extract data from the HTTP response.
template string No Default: none
Use properties from the request response to construct the values of the quick replies that will be displayed to the user.

static

You can use an custom entity that is already defined in the context as a data source. If the entity is not an array of strings, you can use the selector and template properties to construct the list of options that will be displayed to the user.

Let’s say you already have a webhookData entity in the context where you have stored the result from an external API call.

{
  "webhookData": {
    "Doctors": [
      {
        "Title": "Dr.",
        "FirstName": "John",
        "LastName": "Burke"
      },
       {
        "Title": "Dr.",
        "FirstName": "Marry",
        "LastName": "Cannon"
      }
    ],
    "Hospitals":[]
  }
}

Since the webhookData entity is an object, you have to use a selector to get the Doctors array from it. After that using the template property you can format the text of the quick reply options.

{
  "steps": [
    {
      "type": "question",
      "entity": "selectedDoctor",
      "entity-type": "Doctor",
      "messages": [
        "What's the name of the doctor that you want to see?"
      ],
      "display": {
        "type": "quick-reply",
        "data-source": {
          "entity": "webhookData",
          "selector": "$.Doctors[:]"
        },
        "template": "{{Title}} {{FirstName}} {{LastName}}"
      }
    }
  ]
}
Name Type Required Description
data-source object No Default: none
The title text of a card in the carousel.
entity string No Default: none
The name of the entity that has already value stored in Bot Memory.
selector string No Default: none
If the context entity is not an array, you can use the selector property within the data-source to define a JSONPath expression to extract the array. We recommend you to create your JSONPath expressions using the jsonpath.com.
template string No Default: none
Provide a syntax for displaying the options to the user, e.g. {{FirstName}}. This is the handlebars syntax, same as Formatting for messages.