Documentation about IBM Watson® Assistant for IBM Cloud Pak® for Data has moved. For the most up-to-date versions, see Defining responses by using the JSON editor and Response types reference

Defining responses using the JSON editor

In some situations, you might need to define responses using the JSON editor. (For more information about dialog responses, see Responses). Editing the response JSON gives you direct access to the data that will be returned to the communication channel or custom application.

Generic JSON format

The generic JSON format for responses is used to specify responses that are intended for any messaging channel. This format can be implemented by a custom client application. (This is the format that is used by default for dialog responses defined using the Watson Assistant user interface.)

For information about how to open the JSON editor for a dialog node response from the tool, see Context variables in the JSON editor.

To specify an interactive response in the generic JSON format, insert the appropriate JSON objects into the output.generic field of the dialog node response. The following example shows how you might send a response containing multiple response types (text, an image, and clickable options):

{
  "output": {
    "generic":[
      {
        "response_type": "text",
        "values": [
          {
            "text": "Here are your nearest stores."
          }
        ]
      },
      {
        "response_type": "image",
        "source": "http://example.com/image.jpg",
        "title": "Example image",
        "description": "Some description for the image."
      },
      {
        "response_type": "option",
        "title": "Click on one of the following",
        "options": [
          {
            "label": "Location 1",
            "value": {
              "input": {
                "text": "Location 1"
              }
            }
          },
          {
            "label": "Location 2",
            "value": {
              "input": {
                "text": "Location 2"
              }
            }
          },
          {
            "label": "Location 3",
            "value": {
              "input": {
                "text": "Location 3"
              }
            }
          }
        ]
      }
    ]
  }
}

For more information about how to specify each supported response type using JSON objects, see Response types.

If you are using the Watson Assistant connector, the response is converted at run time into the format expected by the channel (Slack or Facebook Messenger). If the response contains multiple media types or attachments, the generic response is converted into a series of separate message payloads as needed. The connector then sends each message payload to the channel in a separate message.

Note: When a response is split into multiple messages, the Watson Assistant connector sends these messages to the channel in sequence. It is the responsibility of the channel to deliver these messages to the end user; this can be affected by network or server issues.

Native JSON format

In addition to the generic JSON format, the dialog node JSON also supports channel-specific responses written using the native Slack and Facebook Messenger formats. These formats are also supported by the Watson Assistant connector. You might want to use the native JSON formats if you know your workspace will only be integrated with one channel type, and you need to specify a response type that is not currently supported by the generic JSON format.

You can specify native JSON for Slack or Facebook using the appropriate field in the dialog node response:

output.slack: insert any JSON you want to be included in the attachment field of the Slack response. For more information about the Slack JSON format, see the Slack documentation.
output.facebook: insert any JSON you want included in the message.attachment.payload field of the Facebook response. For more information about the Facebook JSON format, see the Facebook documentation.

Response types

The following response types are supported by the generic JSON format.

Image

Displays an image specified by a URL.

Fields {: #

Name	Type	Description	Required?
response_type	enum	`image`	Y
source	string	The URL of the image. The specified image must be in .jpg, .gif, or .png format.	Y
title	string	The title to show before the image.	N
description	string	The text of the description that accompanies the image.	N

Example

This example displays an image with a title and descriptive text.

{
  "output": {
    "generic":[
      {
        "response_type": "image",
        "source": "http://example.com/image.jpg",
        "title": "Example image",
        "description": "An example image returned as part of a multimedia response."
      }
    ]
  }
}

Option

Displays a set of buttons or a drop-down list users can use to choose an option. The specified value is then sent to the workspace as user input.

Fields

Name	Type	Description	Required?
response_type	enum	`option`	Y
title	string	The title to show before the options.	Y
description	string	The text of the description that accompanies the options.	N
preference	enum	The preferred type of control to display, if supported by the channel (`dropdown` or `button`). The Watson Assistant connector currently supports only `button`.	N
options	list	A list of key/value pairs specifying the options from which the user can choose.	Y
options[].label	string	The user-facing label for the option.	Y
options[].value	object	An object defining the response that will be sent to the Watson Assistant service if the user selects the option.	Y
options[].value.input	object	An input object that includes the input text corresponding to the option.	N
options[].value.input.text	string	The text that will be sent to your assistant for the option.	N

Example

This example displays two options:

Option 1 (labeled Buy something) sends a simple string message (Place order), which is sent to the workspace as the input text.
Option 2 (labeled Exit) sends a complex message that includes both input text and an array of intents. The response can include any field that is a valid part of a Watson Assistant message. (For more information about the structure of message input, see the API Reference.)

{
  "output": {
    "generic":[
      {
        "response_type": "option",
        "title": "Choose from the following options:",
        "preference": "button",
        "options": [
          {
            "label": "Buy something",
            "value": {
              "input": {
                "text": "Place order"
              }
            }
          },
          {
            "label": "Exit",
            "value": {
              "input": {
                "text": "Exit"
              },
              "intents": [
                {
                  "intent": "exit_app",
                  "confidence": 1.0
                }
              ]
            }
          }
        ]
      }
    ]
  }
}

Pause

Pauses before sending the next message to the channel, and optionally sends a user is typing event (for channels that support it).

Fields

Name	Type	Description	Required?
response_type	enum	`pause`	Y
time	int	How long to pause, in milliseconds.	Y
typing	boolean	Whether to send the `user is typing` event during the pause. Ignored if the channel does not support this event.	N

Example

This examples sends the user is typing event while pausing for 5 seconds.

{
  "output": {
    "generic":[
      {
        "response_type": "pause",
        "time": 5000,
        "typing": true
      }
    ]
  }
}

Text

Displays text. To add variety, you can specify multiple alternative text responses. If you specify multiple responses, you can choose to rotate sequentially through the list, choose a response randomly, or output all specified responses.

Fields

Name	Type	Description	Required?
response_type	enum	`text`	Y
values	list	A list of one or more objects defining text response.	Y
values.[n].text	string	The text of a response. This can include newline characters ( ) and Markdown tagging, if supported by the channel. (Any formatting not supported by the channel is ignored.)	N
selection_policy	string	How a response is selected from the list, if more than one response is specified. The possible values are `sequential`, `random`, and `multiline`.	N
delimiter	string	The delimiter to output as a separator between responses. Used only when `selection_policy`=`multiline`. The default delimiter is newline ( ).	N

Example

This examples displays a greeting message to the user.

{
  "output": {
    "generic":[
      {
        "response_type": "text",
        "values": [
          { "text": "Hello." },
          { "text": "Hi there." }
        ],
        "selection_policy": "random"
      }
    ]
  }
}