Suggestion

Suggestion is a message type that can be used in engagement chat.

  • Operator assistants give the operator a choice whether to use the message in

    the chat or not.

  • Virtual Assistants immediately send the message to the visitor.

JSON schema

Suggestion message can be described with the following JSON schema:

{
"$schema": "http://json-schema.org/draft-06/schema#",
"title": "AI suggestion message",
"type": "object",
"properties": {
"type": {"const": "suggestion"},
"content": {"type": "string"}
},
"metadata": {
"type": "object"
},
"attachment": {"$ref": "#/definitions/response_card"},
"required": ["content"],
"definitions": {
"response_card": {
"type": "object",
"properties": {
"type": {"const": "single_choice"},
"image_url": {"type": "string", "format": "uri-reference"},
"options": {
"type": "array",
"items": {"$ref": "#/definitions/response_card_option"},
"minItems": 1
}
},
"required": ["type", "options"]
},
"response_card_option": {
"type": "object",
"properties": {
"text": {"type": "string"},
"value": {"type": "string"}
},
"required": ["text", "value"]
}
}
}

Message Structure

On the top level suggestion message has the following structure:

Parameter

Required

Type

Description

type

Yes

String

Must be suggestion.

content

Yes

String

Message that will be sent to chat.

attachment

No

Object

A response card attached to a suggestion. See Response Card Properties below.

metadata

No

Object

Suggestion metadata. See Suggestion Metadata below for more details.

Suggestion Metadata

Suggestion metadata is an optional property that, when specified by an integrator, will be used to customize how a response card is rendered.

Response Cards

A response card contains a set of appropriate responses to a prompt. Use response cards to simplify interactions for your users and increase your bot's accuracy by reducing typographical errors in text interactions. You can send a response card for each suggestion that virtual assistants send to visitors.

The following is a response card:

The visitor user can either type the text or choose from the list of insurance types. This response card is configured with an image, which appears in the client as shown.

Response Card Properties

Parameter

Required

Type

Description

type

Yes

String

Specifies type of chat message attachment. Must be single_choice.

image_url

No

String

URL of an image displayed on top of the response card choices.

options

Yes

Array of Object

Specifies a list of all available choices for the Visitor to choose from. See Response Card Options Format below.

Response Card Options Format

Parameter

Required

Type

Description

text

Yes

String

Text displayed to the visitor as a choice label.

value

Yes

String

Value of the choice sent as a response to the engine upon visitor interaction.

Examples

Simple Suggestion

Following example demonstrates how to specify a simple suggestion without response card in JSON format:

{
"type": "suggestion",
"content": "How many rooms are in your rental?"
}

Suggestion with Response Card

Following example demonstrates how to specify a suggestion with response card, containing three choices and illustrated with a picture, in JSON format:

{
"type": "suggestion",
"content": "What kind of insurance are you interested in?",
"attachment": {
"type": "single_choice",
"image_url": "https://cdn.pixabay.com/photo/2018/01/28/10/05/insurance-3113180_960_720.jpg",
"options": [
{
"text": "Life",
"value": "efil"
},
{
"text": "Home",
"value": "emoh"
},
{
"text": "Car",
"value": "rac"
}
]
}
}

In the example above, if visitor clicks on button Car, the engine will receive back value rac, as specified in value key of the selected option.

Suggestion with Custom Response Card

Following example demonstrates how metadata can be used to tailor the custom response card:

{
"type": "suggestion",
"content": "Tailored suggestion for visitor",
"attachment": {
"type": "single_choice",
"image_url": "https://cdn.pixabay.com/photo/2018/01/28/10/05/chess-3113180_960_720.jpg",
"options": [
{
"text": "Yes",
"value": "1"
},
{
"text": "No",
"value": "0"
}
]
},
"metadata": {
"customer": "Harry Brown",
"location": "London",
"age": 45
}
}

Custom Response Card visual example:

Custom Response Card Renderer Configuration

The custom response card renderer is specified using the public function setChatMessageRenderer of Glia JS SDK. The renderer is a simple function returning an HTML element with the custom response card. Configuration of the custom response card renderer is done using Glia JS SDK.

  • Non-interactive custom message example demonstrates how to build a custom

    response card which needs no additional visitor input.

  • Interactive custom message example demonstrates how to build a custom response

    card with clickable options which behaves just like regular attachment

    message.

Non-interactive custom message example
Non-interactive example payload
Interactive custom message example
Interactive example payload
Non-interactive custom message example
sm.getApi({version: 'v1'}).then(function(api) {
const customCard = message => {
return `
<div
class="custom-card"
style="border: 1px solid black; padding: 10px;"
>
<h4
class="custom-card-title"
style="color: #1cce90;"
title="With colors"
>
Custom Card Image
</h4>
<br/>
<img
class="custom-card-image"
style="width: 200px;"
src="https://storage/example.gif"
alt="Some picture"
title="With a sample image"
/>
<br/>
<br/>
<h4
class="custom-card-title"
style="color: #670405;"
>
Custom Card JSON message
</h4>
<textarea
class="custom-card-message-area"
style="border: none; color: #05505c; width: 190px; font-size: 10px; line-height: 1"
>
${JSON.stringify(message, undefined, 2)}
</textarea>
</div>
`;
};
const createCustomCard = function(metadata) {
const element = document.createElement('div');
element.innerHTML = customCard(metadata);
return element.outerHTML;
};
api.visitorApp.setChatMessageRenderer(function(message) {
if (!message.metadata) {
return false;
}
const customCard = document.createElement('div');
customCard.innerHTML = createCustomCard(message.metadata);
return customCard;
});
});
Non-interactive example payload
{
"type": "suggestion",
"content": "Tailored suggestion for visitor",
"attachment": {
"type": "single_choice",
"image_url": "https://cdn.pixabay.com/photo/2018/01/28/10/05/insurance-3113180_960_720.jpg",
"options": [
{
"text": "Yes",
"value": "1"
},
{
"text": "No",
"value": "0"
}
]
},
"metadata": {
"customer": "Harry Brown",
"location": "London",
"age": 45
}
}
Interactive custom message example
sm.getApi({version: 'v1'}).then(function(api) {
let processedCardContainers = [];
let engagementChat;
const colors = ['#b6454b', '#0097fb', '#cc6a2f', '#9f55a6'];
const sendSelectedChoice = function({selectedText, selectedValue}) {
engagementChat.sendMessage(selectedText, {
attachment: {
type: 'single_choice_response',
selected_option: selectedValue
}
});
};
const buildCardQuestionElm = function(question) {
const cardQuestion = document.createElement('div');
cardQuestion.classList.add('sm-choice-card-question');
cardQuestion.innerHTML = question;
return cardQuestion;
};
const buildCardImageElement = function(imageUrl) {
const cardImage = document.createElement('div');
cardImage.classList.add('sm-choice-card-image-container');
cardImage.innerHTML = `<img src="${imageUrl}" />`;
return cardImage;
};
const buildCardOptions = function(message) {
const cardOptions = document.createElement('div');
cardOptions.classList.add('sm-choice-card-options');
const cardOptionsContainer = document.createElement('div');
message.metadata.policy_numbers.forEach(function(policyNumber, index) {
const option = document.createElement('div');
option.innerHTML = policyNumber;
option.addEventListener('click', function() {
sendSelectedChoice({
selectedText: policyNumber,
selectedValue: `Selected value - ${policyNumber}`
});
processedCardContainers.push(message.id);
});
option.setAttribute(
'style',
`cursor:pointer; background:${colors[index]}; color:white; font-weight:bold;`
);
cardOptionsContainer.appendChild(option);
});
cardOptions.appendChild(cardOptionsContainer);
return cardOptions;
};
api.addEventListener(api.EVENTS.ENGAGEMENT_START, engagement => {
engagementChat = engagement.chat;
});
api.visitorApp.setChatMessageRenderer(function(message) {
if (processedCardContainers.includes(message.id)) {
const element = document.createElement('div');
element.classList.add('custom-policy-number-container');
element.classList.add('sm-operator-chat-box');
const chatTextContainer = document.createElement('div');
chatTextContainer.classList.add('sm-chat-text');
chatTextContainer.innerHTML = message.content;
chatTextContainer.setAttribute('style', 'font-weight:bold; color:red;');
element.appendChild(chatTextContainer);
return element;
}
if (message.metadata && message.metadata.policy_numbers) {
const cardContainer = document.createElement('div');
cardContainer.classList.add('sm-choice-card-container');
cardContainer.appendChild(buildCardQuestionElm(message.content));
cardContainer.appendChild(
buildCardImageElement(message.metadata.image_url)
);
cardContainer.appendChild(buildCardOptions(message));
return cardContainer;
}
});
});
Interactive example payload
{
"type": "suggestion",
"content": "How can we help you?",
"metadata": {
"image_url": "https://s3.amazonaws.com/hosting-elements.glia.com/Glia-OG.png",
"policy_numbers": [
"Policy A7J3PPjE1H",
"Insurance w7H1GFfHzu",
"Payday Loan i12BVb7Wgu",
"Mortgage VVutYTx1MO"
]
}
}