API Answers types

Overview

Depending on the user input, the bot can return four types of answers (This is different from Preset answers, for more information see API Preset Answers). Each of these answers are defined by a set of attributes and parameters.

This page is divided into three parts:

  1. Answer types describes the different types of answers and what kind of attributes they can contain.
  2. Attributes and Parameters describes in detail how attributes and parameters are set. This is illustrated with examples.
  3. Code samples provides a full code sample for each answer type.

Answer types

The four answer types are:

  • answer
    This is the generic answer type.
  • polarQuestion
    The bot returns a PolarQuestion when it requires a user interaction based on a "yes/no" answer.
    In this case, messageList contains the question to display, then displays the options available to the user.
  • multipleChoiceQuestion
    The bot returns a multipleChoiceQuestion when the user must select one of several (more than two) options based on contents.
    In this case, messageList contains the question to display, then displays the options available to the user.
  • extendedContentsAnswer
    This type of answer is specific to Federated Bot implementation. The bot returns an extendedContentsAnswer when it finds external results from the sources configured in the Federated Bot.

For a full code sample of each answer type, see the Code samples section below.

Attributes per answer type

This table describes possible attributes for each answer type. For a detailed description of attributes and their function, see the Attributes and Parameters section below.

Type answer polarQuestion multipleChoiceQuestion extendedContentAnswer
message1 ✔️ ✔️ ✔️ ✔️
messageList ✔️ ✔️ ✔️ ✔️
options   ✔️ ✔️  
actionField ✔️      
actionFieldEvents ✔️      
parameters ✔️      
flags ✔️ ✔️ ✔️ ✔️
attributes ✔️      
source ✔️ ✔️ ✔️ ✔️
suggestedAnswer2 ✔️      
actions2 ✔️      
subAnswers2       ✔️

1 The message attribute is deprecated and indicated here for legacy reference.
2 When this attributes is not used, it is not set in the answer.

Parameters per answer type

The table below shows the parameters allowed in POST conversation/message for each answer type. For a detailed description of parameters and their function, see the Attributes and Parameters section below.

You can only send one parameter to the Chatbot API. If you send more than one, the Chatbot API takes the first one and ignores the others, in the following priority order:

  1. directCall
  2. option
  3. message
Message parameter

This is the general natural language user input.

Option parameter

When a set of possible options is provided to the user in a conversation, you can fill the option parameter to indicate the id of the option they can select.

Direct Call parameter

Use this parameter to force Chatbot to clear the current conversation flow and retrieve a specific intent.

Type message option directCall
answer ✔️   ✔️
polarQuestion ✔️ ✔️ ✔️
multipleChoiceQuestion ✔️ ✔️ ✔️

extendedContentsAnswer

✔️   ✔️

As a directCall breaks the current conversation flow, it is suitable for any situation.

Answer attributes and parameters

This section explains possible attributes and parameters and includes examples of implementation for each. For full answer code samples, see the Code Samples section below.

message

This attribute is DEPRECATED: Use "messageList" instead (see below).

This represents the main response from Chatbot. If the Chatbot API returns multiple messages, this attribute concatenates them, separated by newlines (\n).

Example:

"message": "Hello.\nHow can I help you?"
messageList

This is an array containing a set of responses from Chatbot.

"messageList": ["Hello", "How can I help you?"]
options

Default: null

This is an array of objects that represent options that the Chatbot offers as a response.

Schema of options attribute when it is set:

  • value: Value to send to Chatbot as "option" parameter.
  • label: User-friendly title of the option.
  • attributes*: Only when the option corresponds to a content. Array of attributes of the content, same format as root attributes attribute.
  • revisitableLink*: Only when the option corresponds to a content, the content has a directCall name set, and the option can be revisited (option is offered out of the context of a Dialog). If the content has a directCall name set, use it in order to allow revisiting this content anytime in the conversation. You can send this value as "directCall" parameter to POST conversation/message.
  • directCall*: (DEPRECATED) Only when the option corresponds to a content, the content has a directCall name set, and the option can be revisited (option is offered out of the context of a Dialog). If the content has a directCall name set, use it in order to allow revisiting this content anytime in the conversation. You can send this value as "directCall" parameter to POST conversation/messageImportant: This attribute does not track additional context information from the results (e.g. multiple answers, related content, etc.). Use revisitableLink instead.
Example - options are contents
"options": [
        {
            "value": 4,
            "label": "Vegan",
            "attributes": {
                "SIDEBUBBLE_TEXT": "Vegan meals are available for those customers who exclude from their diets all foods derived from animals, including meat, poultry, fish, shellfish, honey, eggs and dairy products and their by-products.",
                "CHECK_QUESTION": "Are you looking for information regarding our vegan meals?",
                "ANSWER_TEXT": "We supply healthy vegan meals prepared fresh by our chefs.",
                "title": "Vegan meals"  /*If the related content has a directCall name set, use it in order to allow revisiting this content anytime in the conversation. You can send this value as "directCall" parameter to POST conversation/message.  */
            },
 "directCall": "VEGAN_MEALS"
        },
        {
            "value": 5,
            "label": "Nut-free",
            "attributes": {
                "SIDEBUBBLE_TEXT": "While every precaution is taken when preparing nut-free meals, we can not guarantee a nut-free environment. For those traveling with severe allergic reactions, we recommend speaking with the in-flight crew upon boarding.",
                "CHECK_QUESTION": "Are you searching for info regarding nut-free meals?",
                "ANSWER_TEXT": "We supply healthy nut free meals prepared fresh by our chefs.",
                "title": "Nut-free meals"
            }
        }
    ]

 

Example - options are not contents
"options": [
    {
        "value": "yes",
        "label": "Yes"
    },
    {
        "value": "no",
        "label": "No"
    }
]

 

ActionField

The engine returns this information if an action field has advanced display options.

Schema of actionField attribute when it is set:

  • fieldType: Type of variable assigned to the field. Possible values: list, datePicker.
  • disableInput: This defines if the user input is disabled or not.
  • actionFieldID: Unique ID assigned to the action field. actionFieldEvents uses this value to update or disable action fields.
  • variableName: Name of the variable assigned to the field.
  • listValues (Only when the fieldType attribute is set to "list")
    • displayType: Display type of the field (dropdown, buttons).
    • values
      • label: This is the value that the user sees.
      • option: This is the value that the system sends to capture the variable.
Example with list
            "actionField": {
                "fieldType": "list",
                "disableInput": true,
                "actionFieldId": "5bd6fa680970b",
                "variableName": "user_type",
                "listValues": {
                    "displayType": "dropdown",
                    "values": [
                        {
                            "label": [
                                "standard"
                            ],
                            "option": "standard"
                        },
                        {
                            "label": [
                                "vip"
                            ],
                            "option": "vip"
                        }
                    ]
                }
            },

 

Example with datePicker
            "actionField": {
                "fieldType": "datePicker",
                "disableInput": false,
                "actionFieldId": "5c1387457c999",
                "variableName": "date_var"
            },

 

actionFieldEvents

The engine returns this key when there are events related to action events.

Schema of actionFieldEvents attribute when it is set:

  • disable: IDs of the action fields to disable.
  • updateRequestedAction: IDs of the action fields to update, changing the default method from sendMessage to addVariable.
Example
            "actionFieldEvents": {
                "disable": [5bd6fa681350a, 5bd6fa699287c],
                "updateRequestedAction": [
                    "5bd6fa680970b"
                ]
            },

 

parameters

Default: null

This is a set of extra parameters based on the current content. It is used only in content-based answers.

Schema:

  • contents: always set if parameters is set
    • title: (DEPRECATED) Use attributes.title instead. This is the Title of the current content.
    • attributes: (DEPRECATED) Use root attribute attributes instead. Attributes of the content that will be displayed in the Chatbot sidebubble.
    • trackingCode: Always set if parameters is set.
      • clickCode: Tracking code to be send to POST tracking/events, with "click" type.
      • rateCode: Not always set. Tracking code to be send to POST tracking/events, with "rate" type.
    • related: Default: unset. Only set if current content has related contents.
      • id: Value to be send with "option" parameter to POST conversation/message if user selects this option. Check the directCall parameter in this object to allow revisiting content.
      • title: (DEPRECATED) Use attributes.title of this same object instead.
      • revisitableLink: Default: unset. If the related content has a directCall name set, use it in order to allow revisiting this content anytime in the conversation. You can send this value as "directCall" parameter to POST conversation/message.
      • directCall: (DEPRECATED) Default: unset. If the related content has a directCall name set, use it in order to allow revisiting this content anytime in the conversation. You can send this value as "directCall" parameter to POST conversation/messageImportant: This attribute does not track additional context information from the results (e.g. multiple answers, related content, etc.). Use revisitableLink instead.
      • attributes: Same schema as root "attributes" attribute.
Example - answer without related contents
"parameters": {
        "contents": {
            "title": "Vegan meals",
            "attributes": {
                "SIDEBUBBLE_TEXT": [
                    "Vegan meals are available for those customers who exclude from their diets all foods derived from animals, including meat, poultry, fish, shellfish, honey, eggs and dairy products and their by-products.\n</p>\n\n<p>\n\tLight vegan meals may include quinoa or corn salads while full vegan meals might include an assortment of rice, vegetables, fruit, and salad. \n</p>"
                ]
            },
            "trackingCode": {
                "clickCode": "eyJpdiI6InlucaStIODU1SDh1QWlYko1SzJjS1E9PSIsInZhbHVlIjoiRVFKbkZSUXVScVVuSzdRKzY1enhTTzE3MHd1OVpCVVFZRDBMNHpzeitRR3Z0V2I1SzhQcE1nUzlFc3lwSmdsbENjbm55VnpDSmtQeUsyZ0o3S0ZhNWRJSE1UNys4aWFhOUI3REZMSVwvTUlLODZCb21taWkyT3RrQ1lySzFZNHpDc0psalJRNUdcL1FETnFYWWZPRmw2MmRcL0ZKaEwrME43YUpjUmE3NG1UQUhFPSIsIm1hYyI6IjczM2NjMzc0MTU3ZjBkZDk2ZDNjNmNmYWE2ODU4MfZhYmQwMmEyYzFiZTUxMWU5MzE5MjMxZTYzYjdlYjg3ODYifQ==",
                "rateCode": "eyJpdiI6Illxbmb44dWd4ZllRUnpL0Z5OXFvY2ZBPT0iLCJ2YWx1ZSI6IndzdGh4bEV5UzVvR3BQbXVOeDc1XC8yek1leXVOTFVrVmNpU2I1WlVWeEZ4XC9KUUlXcW54ZnFScGZsdU5nSmdEdVI5VVwvWWlXYjY3cnhNb2cyRlFIVGtCRG12bDlJdkVNTTczaXZwaVpRMmVaNm5FbkRSWXQ5YmVoYm5XcTVHMXFqdm82WjIzd2MrXC9RclN3XC9CNlBLTW1jWkhZSHJWZlwvbFM0SmdXK1FIbTJ6WT0iLCJtYWMiOiIwYmYxNTE2NDZjNmIzNjc1N2RlYzcyOGY0ODb4MjZjMTNlYzAzMDkzMjhiOWE5ZGY4NDRhNTgyYzAzNzQ3OWI0In0="
            }
        }
    }

 

Example - answer with related content
"parameters": {
                "contents": {
                    "title": "SimpleContentWithRelated",
                    "attributes": [],
                    "trackingCode": {
                        "clickCode": "eyJpdiI6Ild1WUpcL1kyWXNCR055cWZTdGdMVTdRPT0iLCJ2YWx1ZSI6ImxEVXR5ZCsyaDBsUUxvRW5PeUpseFZ5QmR2YkRtTnFrWVdYVnZjdk5taWVsVEtwNGtaSFlEa01uc2YwV0NwNExEcVwvcnZ2ZUdrbnI1Mmh5WEJ2Zm9JK1dGeXhzMWZBeDFJNk9UWVwvUExiYmN3TUZ5eFh4MVVRdmo3dmpSMkQ5MGJLTllsMzNMM3V1WlhuTWVBQk9HWCt2YjVzTEhTVGxEWHFxOEVqcVgwbnl3PSIsIm1hYyI6ImUyNjA2NjY2YTY3MjJiMjU4OThjNjFjNzVhZDNiNGY4MGFjZTkyNDRkZWQ2YzBlYjMzOTZkMjU5ZGE3NDdhYzUifQ==",
                        "rateCode": "eyJpdiI6IjhYZG1DU29TS1Q2RVU4WVRZM2FmK0E9PSIsInZhbHVlIjoiSUZVRWs1ZmYrTU5Rb1luMHNPQUNkeGZyTWVoOFNSM0N2QnB3Vk9WTkxEXC9FZ2J1RXlmXC9uVWtvalNJcXdIZ1A0cHhpM011NklOaW9nWnE5b3MyNDI3MmlYdU5NU1hUZmV2M2kwVFdFMEJ0VEZSMWtIQStTdHo3cXJ0bmtKVnpXaVdNZW5zRUZrK1dkUTFIXC9cL2tadnlJWUxCSHF2dlVVSG9KV21qdjVaRysxVT0iLCJtYWMiOiI0YTk1Y2M1NWNkMWRkMzhjNTBjN2M5N2NiYmE3NDgxMzE5OTQ3MjBkMGI3YTA1ODcxM2VjY2VhNTQzNWNmNmU1In0="
                    },
                    "related": {
                        "relatedTitle": "You might also be interested in: ",
                        "relatedContents": [
                            {
                                "id": "27",
                                "title": "RelatedContent1",
                                "attributes": {
                                    "ANSWER_TEXT": "RelatedContent1 text",
                                    "title": "RelatedContent1"
                                }
                            },
                            {
                                "id": "32",
                                "title": "RelatedContentWithDirectCall",
                                "attributes": {
                                    "ANSWER_TEXT": "RelatedContentWithDirectCall text",
                                    "DIRECT_CALL": "RelatedContentDirectCallName",
                                    "title": "RelatedContentWithDirectCall"
                                },
                                "directCall": "RelatedContentDirectCallName"
                            }
                        ]
                    }
                }

 

flags

Default: empty array

Flags indicate when the Chatbot returns a preset answer (See API preset answers for a list of flags of predefined answers) as well as behaviour suggestions:

  • "no-ratings" suggests to not display answer rating options to the user in the current answer. If this flag is not set, this does not mean that rate code is available: this must be always checked on "parameters.contents.trackingCode.rateCode" attribute.
  • "obfuscate" suggests to obfuscate the next user input in the UI, because sensitive information is being asked to the user.
attributes

Default: null

If an answer is based on content, this returns a set of attributes for this content, including its title.

"attributes": {
                "SIDEBUBBLE_TEXT": "While every precaution is taken when preparing nut-free meals, we can not guarantee a nut-free environment. For those traveling with severe allergic reactions, we recommend speaking with the in-flight crew upon boarding.",
                "CHECK_QUESTION": "Are you searching for info regarding nut-free meals?",
                "ANSWER_TEXT": "We supply healthy nut free meals prepared fresh by our chefs.",
                "title": "Nut-free meals"
            }
source

Default: {"type": "chatbot","name": "Chatbot"}

This provides information about the source of the answer, based on the configuration of the Federated Bot.

  • type: Source type (chatbot, km, search).
  • name: Name set in Federated Bot settings to the source.

This info is notably useful in the extendedContentsAnswer answer type, because each subAnswer returns its respective source.

Example:

"source": {
        "type": "chatbot",
        "name": "Chatbot"
    }
suggestedAnswer

Default: unset

In a form, Chatbot uses this attribute to suggest a user response. When it asks for the value of a variable and this value is already set, the Chatbot returns this attribute completed.

Example:

"suggestedAnswer": "johndoe@testdomain.com"
actions

Default: unset

When it finishes a form where a JS Callback is set, the Chatbot returns an array of actions with the following schema:

  • name: Type of the action. Right now, only "callback" value is used.
  • parameters:
    • callback: Name of the callback (set in Backstage).
    • data: Key-value object containing Parameter name as Key, and its value. If form has no parameters, empty array.

 

"actions": [
    {
        "name": "callback",
        "parameters": {
            "callback": "test",
            "data": []
        }
    }
]
subAnswers

Default: unset

This is an array of answers from external sources. Each answer has exactly the same schema as an answer.

Each subAnswer contains the source of its external source.

subAnswers
"subAnswers": [
      {
        "type": "answer",
        "message": "Round Metal 0RB3447 001",
        "options": null,
        "parameters": {
          "contents": {
            "title": "Round Metal 0RB3447 001",
            "attributes": {
              "SIDEBUBBLE_TEXT": [
                "Lens Material: Crystal Standard; Lens Material: crystal green; 
                 Frame Material: metal; Frame Color: arista; Size: 50; Color: 001"
              ]
            }
          }
        },
        "flags": [],
        "attributes": {
          "ANSWER_TEXT": "Round Metal 0RB3447 001",
          "SIDEBUBBLE_TEXT": "Lens Material: Crystal Standard; Lens Material: crystal green; 
           Frame Material: metal; Frame Color: arista; Size: 50; Color: 001"
        },
        "source": {
          "type": "external_search",
          "name": "Product Data Search API"
        }
      },
      {
        "type": "answer",
        "message": "Aviator Large Metal 0RB3025 w3277",
        "options": null,
        "parameters": {
          "contents": {
            "title": "Aviator Large Metal 0RB3025 w3277",
            "attributes": {
              "SIDEBUBBLE_TEXT": [
                "Lens Material: Crystal Standard; Lens Color: crystal grey mirror; 
                 Frame Material: metal; Frame Color: silver; Size: 58; Color: w3277"
              ]
            }
          }
        },
        "flags": [],
        "attributes": {
          "ANSWER_TEXT": "Aviator Large Metal 0RB3025 w3277",
          "SIDEBUBBLE_TEXT": "Lens Material: Crystal Standard; Lens Color: crystal grey mirror; 
           Frame Material: metal; Frame Color: silver; Size: 58; Color: w3277"
        },
        "source": {
          "type": "external_search",
          "name": "Product Data Search API"
        }
      }
  ]

 

Code samples

answer
answer
{
    "type": "answer",
    "message": "Hello! Is there anything I can do for you?",
    "messageList": [
        "Hello! Is there anything I can do for you?"
    ],
    "options": null,
    "parameters": null,
    "flags": [],
    "attributes": null,
    "source": {
        "type": "chatbot",
        "name": "Chatbot"
    }
}

 

polarQuestion
polarQuestion
{
    "type": "polarQuestion",
    "message": "Do you want to know more information about musical instruments baggage?",
    "messageList": [
        "Do you want to know more information about musical instruments baggage?"
    ],
    "options": [
        {
            "value": "yes",
            "label": "Yes"
        },
        {
            "value": "no",
            "label": "No"
        }
    ],
    "parameters": null,
    "flags": [],
    "attributes": {
        "CHECK_QUESTION": "Are you looking for information about musical instruments baggage?",
        "ANSWER_TEXT": "<p>\n\tMusical instruments which weigh more than 70 lbs may only be taken on ACME Airlines flights after registration and approval.\n</p>",
        "title": "Oversized baggage: musical instruments"
    },
    "source": {
        "type": "chatbot",
        "name": "Chatbot"
    }
}

 

multipleChoiceQuestion
multipleChoiceQuestion
{
    "type": "multipleChoiceQuestion",
    "message": "Please choose the type of special meal that interests you.",
    "messageList": [
        "Please choose the type of special meal that interests you."
    ],
    "options": [
        {
            "value": 4,
            "label": "Vegan",
            "attributes": {
                "SIDEBUBBLE_TEXT": "Vegan meals are available for those customers who exclude from their diets all foods derived from animals, including meat, poultry, fish, shellfish, honey, eggs and dairy products and their by-products.",
                "CHECK_QUESTION": "Are you looking for information regarding our vegan meals?",
                "ANSWER_TEXT": "We supply healthy vegan meals prepared fresh by our chefs.",
                "title": "Vegan meals"
            }
        },
        {
            "value": 5,
            "label": "Nut-free",
            "attributes": {
                "SIDEBUBBLE_TEXT": "While every precaution is taken when preparing nut-free meals, we can not guarantee a nut-free environment. For those traveling with severe allergic reactions, we recommend speaking with the in-flight crew upon boarding.",
                "CHECK_QUESTION": "Are you searching for info regarding nut-free meals?",
                "ANSWER_TEXT": "We supply healthy nut free meals prepared fresh by our chefs.",
                "title": "Nut-free meals"
            }
        }
    ],
    "parameters": null,
    "flags": [],
    "attributes": null,
    "source": {
        "type": "chatbot",
        "name": "Chatbot"
    }
}

 

extendedContentsAnswer
extendedContentsAnswer
{
  "type": "extendedContentsAnswer",
  "message": "Click any option:", //can be empty if the client did not fill the "Initial text" field for the current base
  "subAnswers": [
      {
        "type": "answer",
        "message": "Round Metal 0RB3447 001",
        "options": null,
        "parameters": {
          "contents": {
            "title": "Round Metal 0RB3447 001",
            "attributes": {
              "SIDEBUBBLE_TEXT": [
                "Lens Material: Crystal Standard; Lens Material: crystal green; 
                 Frame Material: metal; Frame Color: arista; Size: 50; Color: 001"
              ]
            }
          }
        },
        "flags": [],
        "attributes": {
          "ANSWER_TEXT": "Round Metal 0RB3447 001",
          "SIDEBUBBLE_TEXT": "Lens Material: Crystal Standard; Lens Material: crystal green; 
           Frame Material: metal; Frame Color: arista; Size: 50; Color: 001"
        },
        "source": {
          "type": "external_search",
          "name": "Product Data Search API"
        }
      },
      {
        "type": "answer",
        "message": "Aviator Large Metal 0RB3025 w3277",
        "options": null,
        "parameters": {
          "contents": {
            "title": "Aviator Large Metal 0RB3025 w3277",
            "attributes": {
              "SIDEBUBBLE_TEXT": [
                "Lens Material: Crystal Standard; Lens Color: crystal grey mirror; 
                 Frame Material: metal; Frame Color: silver; Size: 58; Color: w3277"
              ]
            }
          }
        },
        "flags": [],
        "attributes": {
          "ANSWER_TEXT": "Aviator Large Metal 0RB3025 w3277",
          "SIDEBUBBLE_TEXT": "Lens Material: Crystal Standard; Lens Color: crystal grey mirror; 
           Frame Material: metal; Frame Color: silver; Size: 58; Color: w3277"
        },
        "source": {
          "type": "external_search",
          "name": "Product Data Search API"
        }
      }
  ],
  "parameters": null,
  "flags": [],
  "attributes": null,
  "source": {
    "type": "chatbot",
    "name": "chatbot"
  }
}