Send a Message
In its simplest form, the backend expects a plain text message written in a natural language and when sending this message, it is important to add the sessionId and klevuApiKey in the context.
Request:
With every message sent to the backend, in its response, it will always return the context containing the respective sessionId and the klevuApiKey. Additionally, it may come back with different types of data elements. It may look like the following with one or more elements of each type.
Response:
Lets have a look at each data type in the response :
Parameter | Description |
|---|---|
sessionId | The sessionId assigned to the current user and should be used for any subsequent interactions by this user. |
klevuApiKey | The Klevu API key used for the session. |
Parameter | Description |
|---|---|
id | Every message is assigned a unique id. This is used when submitting shopper’s feedback for this particular message. We will see an example of the same a bit later in the document. |
type | In the current version, the value of this remains as "text". |
value | The message you want to show to the shopper. The value here is usually a plain text but can also contain URLs and therefore the respective html anchors in it. |
note | This is like a fine print or an instruction or a general note that you may want to show as a fine print to the current message. |
explain | Why the system has produced the answer it has, the explanation of the same is provided in this element. It details the reasoning the backend system has followed. In our UIs we show them behind the info icon. |
collectFeedback | If set to true, this is an instruction to the frontend that feedback should be collected for this particular message. |
There can be one or more of this in a single request. When rendering messages on the front, please show them in the order they are provided in the response.
These are different filtering options the MOI backend likes to present to the shopper and ask to choose from. For example, if a shopper has asked for dresses, the MOI application may want to show some colors or sizes or other attributes to collect shopper’s preferences.
Parameter | Description |
|---|---|
label | Shows a message to be shown to the shopper before listing down the options. |
key | The id/key of the filter. |
chatFormat | When a shopper has selected an option, there are two things we like to do.
The chatFormat here shows the template that can be used to prepare a message that should be shown to the shopper. Here, for example, the chat format is "$VALUE$ please!". The $VALUE$ should be replaced with the actual option (or options) selected. For example "small and medium please!".
|
chatFormatEmpty | This is for future reference and can be ignored for now. |
Parameter | Description |
|---|---|
name | Caption of the option (e.g. "s", "m"). |
value | If a customer chooses this option, the value to be sent to the backend. We will see later in the documentation how to use this value. |
selected | If this option was already selected by the shopper. It comes as true or false/null. |
count | The number of products MOI has for this option. |
This is where the actual products to be shown to the shopper are sent from the MOI backend. For each product it shows some product specific options as well.
Parameter | Description |
|---|---|
products | The array of individual data points for each of the product records (see productData.products section below). |
totalResultsFound | the total number of results found. |
typeOfQuery | You may ignore this as this is only used for debugging. |
note | A fine print that you may want to show to the shopper. |
Parameter | Description |
|---|---|
id | The unique id of the product. |
itemRef | This is a product locator (e.g. p0 and p1). Shoppers can include these references in their question. |
itemGroupId | The parent group id of the product. In case of a product having multiple variants, a group id is associated with every variant. |
image | The URL of the image to be used to fetch product image. |
name | The title of the product. |
url | URL of the product. |
price | Retail price of the product. |
salePrice | Price after discount. |
currency | 3 letter currency code. |
shortDesc | Short description of the product. |
originalContent | Long description of the product. |
noOfVariants | If there are other variants of this product available. This field contains the count of these variants. |
options | The options to be shown in the UI for this product. For each option, it contains the following sub elements: |
options.name | Caption for the option. |
options.intent | When a shopper clicks on this option and when you send a call to answer this click, it will require you to submit the intent. How exactly such a product specific option be handled is explained later in the document. |
options.chat | The message to be posted in the chat window when handling this option. |
These are different dynamic options that are relevant in the current state after the last response was sent. In our UIs, we convert them into buttons.
Parameter | Description |
|---|---|
name | This is like a caption of a button |
type | There are two types supported: message: if the type is “message”, when a shopper clicks on it, the associated chat should be posted in the chat window and sent as a message to the MOI backend. clearChat: if the type is “clearChat”, the chat UI should be cleared. No need to send any message to the MOI backend. |
chat | When a shopper hits on the button for these options, the text provided here should be posted in the chat window and sent as a message to the MOI backend. |
The MOI backend may want you to take certain actions such as redirect shoppers to a particular page or collect their order number for order tracking etc. For such matters, it may include certain information in the response.
Here, for example, the action is to redirect the shopper to a particular URL.
Parameter | Description |
|---|---|
actions | There maybe more than one action available. |
type | There action type. |
context | The action context. |
