Depending on the user input, the bot can return four types of answers (This is different from Preset answers, for more information see API Direct Answers). Each of these answers are defined by a set of attributes and parameters.
This page is divided into three parts:
The four answer types are:
For a full code sample of each answer type, see the Code samples section below.
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 | ✔️ | |||
parameters3 | ✔️ | ✔️ | ||
flags | ✔️ | ✔️ | ✔️ | ✔️ |
attributes | ✔️ | |||
source | ✔️ | ✔️ | ✔️ | ✔️ |
suggestedAnswer2 | ✔️ | |||
actions2 | ✔️ | |||
subAnswers2 | ✔️ | |||
intent2 | ✔️ | ✔️ | ||
logId | ✔️ |
1 The message attribute is deprecated and indicated here for legacy reference.
2 When this attribute is not used, it is not set in the answer.
3 MultipleChoiceQuestion answer types only have parameters when they are returned as part of post-response behavior.
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 Chat API. If you send more than one, the Chat API takes the first one and ignores the others, in the following priority order:
This is the general natural language user input.
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. This parameter is only permitted immediately after the Chat returns a response that is either a multipleChoiceQuestion or a polarQuestion. After the next user interaction (e.g. an input or a click), the "option" parameter is no longer valid: Make sure the implementation does not send this parameter to the API again.
Use this parameter to force Chat 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.
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.
This attribute is DEPRECATED: Use "messageList" instead (see below).
This represents the main response from Chat. If the Chat API returns multiple messages, this attribute concatenates them, separated by newlines (\n).
Example:
"message": "Hello.\nHow can I help you?"
This is an array containing a set of responses from Chat.
"messageList": ["Hello", "How can I help you?"]
Default: null
This is an array of objects that represent options that the Chat offers as a response.
Schema of the options attribute when it is set:
POST conversation/message
.
The following attribute is DEPRECATED. Use revisitableLink instead.
POST conversation/message
. Important: This attribute does not track additional context information from the results (e.g. multiple answers, related content, etc.).
"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.", "ALTERNATIVE_TITLE": [ "Vegan meals on board", "Vegetarian meals on board" ], "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. */ "inbMainTitle": "Vegan meals" }, "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.", "ALTERNATIVE_TITLE": [ "Nut-free meals on board" ], "title": "Nut-free meals on board", /*Title that matched the user question*/ "inbMainTitle": "Nut-free meals" } } ]
"options": [ { "value": "yes", "label": "Yes" }, { "value": "no", "label": "No" } ]
The engine returns this information if an action field has advanced display options.
Schema of the actionField attribute when it is set:
actionFieldEvents
uses this value to update or disable action fields.
This attribute remains empty until you publish all intents at least once to Development.
"actionField": { "fieldType": "list", "disableInput": true, "actionFieldId": "5bd6fa680970b", "variableName": "user_type", "dataType": "string", "listValues": { "displayType": "dropdown", "values": [ { "label": [ "standard" ], "option": "standard" }, { "label": [ "vip" ], "option": "vip" } ] } },
"actionField": { "fieldType": "datePicker", "disableInput": false, "actionFieldId": "5c1387457c999", "variableName": "date_var", "dataType": "date" },
The engine returns this key when there are events related to action events.
Schema of actionFieldEvents attribute when it is set:
sendMessage
to addVariable.
"actionFieldEvents": { "disable": [5bd6fa681350a, 5bd6fa699287c], "updateRequestedAction": [ "5bd6fa680970b" ] },
Default: null
This is a set of extra parameters based on the current content. It is used only in content-based answers.
Schema:
Some of the following attributes are DEPRECATED.
POST tracking/events
, with "click" type.
rateCode: Not always set. Tracking code to be send to POST tracking/events
, with "rate" type.
POST conversation/message
if user selects this option. Check the directCall parameter in this object to allow revisiting content.
POST conversation/message
.
POST conversation/message
. Important: This attribute does not track additional context information from the results (e.g. multiple answers, related content, etc.). Use revisitableLink instead.
"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=" } } }
"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" } ] } }
Default: empty array
Flags indicate when the Chat returns a preset answer (See API direct answers for a list of flags of predefined answers) as well as behavior suggestions:
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.", "ALTERNATIVE_TITLE": [ "Nut-free meals on board" ], "title": "Nut-free meals", "inbMainTitle": "Vegan meals" }
Default: {"type": "chat","name": "Chat"}
This provides information about the source of the answer, based on the configuration of the Federated Bot.
This info is notably useful in the extendedContentsAnswer answer type, because each subAnswer returns its respective source.
Example:
"source": { "type": "chat", "name": "Chat" }
Default: unset
In a form, Chat uses this attribute to suggest a user response. When it asks for the value of a variable and this value is already set, the Chat returns this attribute completed.
Example:
"suggestedAnswer": "johndoe@testdomain.com"
Default: unset
When it finishes a form where a JS Callback is set, the Chat returns an array of actions with the following schema:
"actions": [ { "name": "callback", "parameters": { "callback": "test", "data": [] } } ]
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 external source.
"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" }, "intent": { "type": "External", "score": 0.984574 } }, { "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" }, "intent": { "type": "External", "score": 0.42326 } } ]
Default: unset
Returns a new attribute with the following schema:
The bot returns this attribute in the following cases:
The attribute always returns the type. It only returns the score when the bot returns the intent after a semantic search. This means that if the user clicks on the result instead of typing their choice, no score is returned.
Default: null
Returns a string with the search log id. The logId can be used to add tracking events to a user search, meaning to track external Content Management System contents.
"logId": "141,123456929053505347"
{ "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": "chat", "name": "Chat" }, "logId": "141,123456929053505347" }
{ "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>", "ALTERNATIVE_TITLE": [ "Check-in a double bass", "Check-in a guitar", "Check-in a drum set" ], "title": "Oversized baggage: musical instruments", "inbMainTitle": "Oversized baggage: musical instruments" }, "source": { "type": "chat", "name": "Chat" }, "logId": null }
{ "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": "chat", "name": "Chat" }, "logId": null }
{ "type": "multipleChoiceQuestion", "message": "There is more than one answer which may help you find the information you need. Please click on the highlighted answers below for more detail:", "messageList": [ "There is more than one answer which may help you find the information you need. Please click on the highlighted answers below for more detail:" ], "options": [ { "value": 4, "label": "Buy a car", "attributes": { "ANSWER_TEXT": "All you need to know about buying a car from dealers and private sellers.", "ALTERNATIVE_TITLE": [ "Book a car" ] "title": "Buy a car", "inbMainTitle": "Buy a car" }, "intent": { "type": "KB", "score": 0.984574 } }, { "value": 5, "label": "All what you need to know before buying a car", "attributes": { "ANSWER_TEXT": "Buy a car: top ten tips", "ALTERNATIVE_TITLE": [ "All what you need to know before buying a car", "The ultimate guide to buy a car" ] "title": "All what you need to know before buying a car", "inbMainTitle": "Buy a car: top ten tips" }, "intent": { "type": "KB", "score": 0.872323 } } ], "parameters": null, "flags": [], "attributes": null, "source": { "type": "chat", "name": "Chat" }, "logId": null }
{ "type": "extendedContentsAnswer", // This value means that the result comes from another source "message": "Click any option:", // Can be empty if the client did not fill the "Initial text" field for the current base "messageList": [ "Click any option:" ], "options": null, "parameters": null, "flags": [], "attributes": null, "source": { "type": "chat", "name": "Chat" }, "subAnswers": [ // If included, the subAnswers array contains the federated results { "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": "chat", "name": "chat" }, "logId": null }