Types of Rich Messages

Here is a list of available Rich Messages you can use in Kommunicate chat:

• Buttons
  • Link Buttons
  • Submit Buttons
  • Suggested Replies
• Images
• List
• Cards
  • Generic Card
  • Card Carousel
• Form

Buttons

You can add any number of Buttons in your conversations for faster navigation. There are three types of Buttons separated by their action.

Link Button

Link Button redirects users to a given URL in a new tab.

Use the below metadata to render the Link Buttons:

{
    "message": "click on the buttons",
    "platform":"kommunicate",
    "metadata": {
        "contentType": "300",
        "templateId": "3",
        "payload": [{
                "type": "link",
                "url": "https://www.google.com",
                "name": "Go To Google"
            },
            {
                "type": "link",
                "url": "https://www.facebook.com",
                "name": "Go To Facebook",
                "openLinkInNewTab": false
            }
        ]
    }
}

Use openLinkInNewTab: false to open any link in the same tab. Default value is true, which will open the links in the new tab.

Submit Button

Submit Button allows you to post given data or redirect the user to a given URL. If parameter requestType:json is included, it will post the data with content type application/json on the formAction URL and the replyText will be used as acknowledgement message.

Default value for replyText is same as the value passed in name parameter. If requestType parameter is not passed, it will submit the formData with contentType application/x-www-form-urlencoded and redirect the user on formAction URL. The response will be rendered in new tab.

{
    "message": "click the pay button",
    "platform": "kommunicate",
    "metadata": {
        "contentType": "300",
        "templateId": "3",
        "payload": [{
            "name": "Pay",
            "replyText":"optional, will be used as acknowledgement message to user in case of requestType JSON. Default value is same as name parameter"
        }],
        "formData": {
            "amount": "1000",
            "description": "movie ticket"
        },
        "formAction": "https://example.com/book",
        "requestType":"json"
    }
}

Suggested Replies

Suggested Replies provide a way to send messages on a click without typing them all out manually. These are essentially the same as Suggestion Chips in Dialogflow and Postback Buttons in Facebook.

Note: Suggested Replies were previously called Quick Replies.

You can add any number of Suggested Replies by passing values in the metadata as described below:

{
    "message": "Do you want more updates?",
    "platform": "kommunicate",
    "metadata": {
        "contentType": "300",
        "templateId": "6",
        "payload": [{
            "title": "Yes",
            "message": "Cool! send me more."
        }, {
            "title": "No",
            "message": "Not at all",
            "replyMetadata": {
                "KM_CHAT_CONTEXT": {
                    "buttonClicked": true
                }
            }
        }]
    }
}

replyMetadata helps you to send custom data along with every suggested reply. Pair it with KM_CHAT_CONTEXT to receive data back when user click on the suggested reply. The appearance of the Suggested Replies and Buttons will be adjusted automatically according to the customization you have done on your chat widget.

Combine different type of buttons with single message

Note : Support for combining different type of buttons is in progress for mobile SDKs. If you are using this payload it will not render any button on mobile SDKs as of now.

To combine the different buttons with single message you can put the payload of different button in a single array. Below example demonstrate how to achieve this :

{
  "message": "This example shows how to combine different buttons with a message",
  "platform": "kommunicate",
  "metadata": {
    "contentType": "300",
    "templateId": "11",
    "payload": [
      {
        "name": "Link button",
        "action": {
          "type": "link",
          "url": "https://www.facebook.com",
          "openLinkInNewTab": false
        }
      },
      {
        "name": "submit button",
        "action": {
          "type": "submit",
          "message": "optional- this message will be used as acknowledgement text when user clicks the button",
          "formData": {
            "amount": "1000",
            "description": "movie ticket"
          },
          "formAction": "https://example.com/book",
          "requestType": "json"
        }
      },
      {
        "name": "Suggested reply Button",
        "action": {
          "type": "quickReply",
          "message": "text will be sent as message"
        },
        "replyMetadata": {
          "KM_CHAT_CONTEXT": {
            "key": "value"
          }
        }
      }
    ]
  }
}

Images

Images can be rendered in conversation using below JSON. The image object contains a caption(optional) and an image URL. You can send a list of image objects in the payload. There is no action supported on image template.

{
  "message": "Hey I am Kommunicate support bot",
  "platform":"kommunicate",
  "metadata": {
    "contentType": "300",
    "templateId": "9",
    "payload": [
      {
        "caption": "Image caption",
        "url": "Image URL"
      }]
  }
}

List Template

The list template is a list of structured items with an optional header image and header text.

Components of a List Template

A list template may contain below items:

• Header Image   (Recommended size: 910*330px)

• Header text   (Character limit: 75)

• List of items: Each item may contain below components:

  • Thumbnail image  (Recommended size: 150*150px)
  • Title   (Character limit: 32)
  • Description   (Character limit: 35)
  • The action of the item

• List of buttons: Each button may contain below components:

  • Name of button
  • The action of the button

Actions on the List

There are two types of action supported on list items and buttons.

• Link: It will navigate the user to another page in a new tab.

• Suggested Replies: It will send a message with given text if passed. The default value will be the title of the list item or name of the button. The action is specified by the action object passed along with each item and button. This is how the action object looks like :

// for Suggested Reply, the action object will look like this:
"action": {
    "type": "quick_reply",
    "text": "This text will be sent as message"
}

// for Link, the action object will look like this:
"action": {
    "type": "link",
    "url": "URL to navigate other page"
}

Note: Any URL provided in url key above will open that URL in a new tab.

Here is the sample JSON for the List Template:

{
    "message": "This is the sample json for list template",
    "platform": "kommunicate",
    "metadata": {
        "contentType": "300",
        "templateId": "7",
        "payload": {
            "headerImgSrc": "URL for header image",
            "headerText": "Header text.",
            "elements": [{
                "imgSrc": "Thumbnail icon for list item",
                "title": "List item 1",
                "description": "Description for the list item",
                "action": {
                    "url": "https://www.google.com",
                    "type": "link"
                }
            }],
            "buttons": [{
                "name": "See us on facebook",
                "action": {
                    "url": "https://www.facebook.com",
                    "type": "link"
                }
            }]
        }
    }
}

Cards

The card template is a list of structured items with title, subtitle, image, and buttons. There are two types of Cards supported in Kommunicate:

• Generic Card
• Carousel Card

Generic Card

Components of card template

A card template may contain below items:

• Header
  • Image (optional)    (Recommended size: 720*280px)
  • Overlay text (optional)
• Card information section
  • Title    (Character limit: 16)
  • Title extension (optional)
  • Subtitle    (Character limit: 56)
  • Description    (Character limit is 99 and use \n to break the line.)
• Card footer may contain a list of buttons, it can be:
  • Link Button
  • Submit Button
  • Suggested Replies

Actions on the button

• Link: It will navigate the user to another page in a new tab.

• Submit Button: Submit Button allows you to post given data or redirect the user to a given URL.

• Suggested Replies: It will send a message with given text if passed. The default value will be the title of the list item or name of the button. The action is specified by the action object passed along with each item and button.
  

Here are the actions you can perform on click of the buttons:

Sample "action" object for Suggested Reply:

"action": {
    "type": "quickReply",
    "payload": {
        "title": "Yes",
        "message": "text will be sent as message",
    }
}

Sample "action" object for navigation link:

"action": {
    "type": "link",
    "payload": {
        "url": "https://www.facebook.com"
    }
}

Sample "action" object for Submit Button:

"action": {
    "type": "submit",
    "payload": {
        "text": "Button text",
        "formData": {
            "amount": "1000",
            "description": "movie ticket"
        },
        "formAction": "https://example.com/book",
        "requestType": "json"
    }
}

Here is the sample JSON for the single card:

{
  "message": "This is the sample json for card template",
  "platform": "kommunicate",
  "metadata": {
    "contentType": "300",
    "templateId": "10",
    "payload": [
      {
        "title": "Card Title",
        "subtitle": "Card Subtitle ",
        "header": {
          "overlayText": "Overlay Text",
          "imgSrc": "Header image for the card"
        },
        "description": "Description",
        "titleExt": "Title extension",
        "buttons": [
          {
            "name": "Link Button",
            "action": {
              "type": "link",
              "payload": {
                "url": "https://www.facebook.com"
              }
            }
          }
        ]
      }
    ]
  }
}

You can add any number of buttons in your card footer.

Card Carousel

The Kommunicate chat widget supports sending of a horizontally scroll-able carousel of generic templates.

The payload is an array of objects, each object can be different cards. So you can pass multiple objects inside the payload.

Here is the sample JSON for the card carousel:

{
  "message": "Carousel",
  "platform": "kommunicate",
  "metadata": {
    "contentType": "300",
    "templateId": "10",
    "payload": [
      {
        "title": "OYO Rooms 1",
        "subtitle": "Kundanahalli road turn.",
        "header": {
          "overlayText": "$400",
          "imgSrc": "http://www.tollesonhotels.com/wp-content/uploads/2017/03/hotel-room.jpg"
        },
        "description": "Bharathi Road \n Near Head Post Office",
        "titleExt": "4.2/5",
        "buttons": [
          {
            "name": "Link Button",
            "action": {
              "type": "link",
              "payload": {
                "url": "https://www.facebook.com"
              }
            }
          },
          {
            "name": "Suggested Reply",
            "action": {
              "type": "quickReply",
              "payload": {
                "message": "text will be sent as message",
                "replyMetadata": {
                  "key1": "value1"
                }
              }
            }
          },
          {
            "name": "Submit button",
            "action": {
              "type": "submit",
              "payload": {
                "text": "acknowledgement text",
                "formData": {
                  "amount": "$55",
                  "description": "movie ticket"
                },
                "formAction": "https://example.com/book",
                "requestType": "json"
              }
            }
          }
        ]
      },
      {
        "title": "OYO Rooms 2",
        "subtitle": "Kundanahalli ",
        "header": {
          "overlayText": "$360",
          "imgSrc": "http://www.tollesonhotels.com/wp-content/uploads/2017/03/hotel-room.jpg"
        },
        "description": "Bharathi Road | Near Head Post Office, Cuddalore 607001",
        "titleExt": "4.2/5",
        "buttons": [
          {
            "name": "Link Button",
            "action": {
              "type": "link",
              "payload": {
                "url": "https://www.facebook.com"
              }
            }
          },
          {
            "name": "Submit button",
            "action": {
              "type": "submit",
              "payload": {
                "text": "acknowledgement text",
                "formData": {
                  "amount": "$22",
                  "description": "movie ticket"
                },
                "formAction": "https://example.com/book",
                "requestType": "json"
              }
            }
          },
          {
            "name": "Suggested Reply",
            "action": {
              "type": "quickReply",
              "payload": {
                "message": "text will be sent as message",
                "replyMetadata": {
                  "key1": "value1"
                }
              }
            }
          }
        ]
      },
      {
        "title": "OYO Rooms 3",
        "subtitle": "Kundanahalli ",
        "header": {
          "overlayText": "$750",
          "imgSrc": "http://www.tollesonhotels.com/wp-content/uploads/2017/03/hotel-room.jpg"
        },
        "description": "Bharathi Road | Near Head Post Office, Cuddalore 607001",
        "titleExt": "4.2/5",
        "buttons": [
          {
            "name": "Link Button",
            "action": {
              "type": "link",
              "payload": {
                "url": "https://www.facebook.com"
              }
            }
          },
          {
            "name": "Submit button",
            "action": {
              "type": "submit",
              "payload": {
                "text": "acknowledgement text",
                "formData": {
                  "amount": "$45",
                  "description": "movie ticket"
                },
                "formAction": "https://example.com/book",
                "requestType": "json"
              }
            }
          },
          {
            "name": "Suggested Reply",
            "action": {
              "type": "quickReply",
              "payload": {
                "message": "text will be sent as message",
                "replyMetadata": {
                  "key1": "value1"
                }
              }
            }
          }
        ]
      }
    ]
  }
}

Use autosuggestions in your chat box

Autosuggestions make your users' life easier by populating the list of possible answers/data in the chat itself (see the image below).

If you want to ask any question or enter any text message into the chat box and send possible answers or list of data with that question, you can pass a list of answers or data into metadata. It will be displayed in the suggestion list. Suggestion list can also be fetched from a source URL/server if you pass source URL into the message.

The format of the message is as below:

{
  "message": "Where do you wanna go this summer?",
  "platform": "kommunicate",
  "metadata": {
    "KM_AUTO_SUGGESTION": {
      "placeholder": "enter city name ",
      "source": []
    }
  }
}

"placeholder" (optional) will appear in the chat input field as placeholder text. The "source" can be any one of the below formats:

• Array of string

{
    "source": [
        "London",
        "New York",
        "Delhi"
    ]
}

• Array of object

{
    "source": [{
            "searchKey": "Photography",
            "message": "Photography Lessons"
        },
        {
            "searchKey": "passport visa Services",
            "message": "Passport & Visa Services"
        }
    ]
}

• Url: Pass the API endpoint to get the data. Kommunicate will send data in the query parameter.

{
  "source": {
    "url": "<API_ENDPOINT>",
    "headers": {}
  }
}

The API should return data in below format :

[
  {
    "searchKey": "searchable value",
    "name": "Text message which you want display/send into conversation.",
    "metadata": { "key": "value" } //optional, any extra information you want to send with message
  }
]

"metadata" is any extra information you want to send with the message. This field is optional.

Send HTML content

HTML content will work with V2 APIs.

You can send HTML content as a message and Kommunicate will render the HTML in the UI. Pass the property messageType: html in custom payload from Dialogflow. You can send a standalone HTML message or combine it with Rich Messages. Below is the sample JSON with Suggested Replies:

Sample JSON with HTML in Suggested Replies:

{
    "message": "<ul><li> Bangalore </li><li> California </li><li> Singapore </li><li> London </li></ul>",
    "platform": "kommunicate",
    "messageType":"html",
    "metadata": {
        "contentType": "300",
        "templateId": "6",
        "payload": [{
            "title": "Show More",
            "message": "Show me more"
        }]
    }
}

Form Template

You can add forms in your messages to collect information from users. The data filled by the user can be sent back to your bot or a URL to process it further.

parameter	description
requestType	It is optional, by default it will allow you to post form data to a given formAction URL and values are json : it will post the form data with content type application/json on the formAction URL. postBackToBotPlatform : it will send form data back to bot platform. formAction can be empty in case of postBackToBotPlatform.
replyText	It will be used as acknowledgement message.

Some of the supported input types:

• Text
• Password
• Hidden
• Radio Buttons
• Checkbox

here is the sample JSON for the form template:

{
  "message": "Submit your details",
  "platform": "kommunicate",
  "metadata": {
    "contentType": "300",
    "templateId": "12",
    "payload": [
      {
        "type": "text",
        "label": "Name",
        "placeholder": "Enter your name"
      },
      {
        "type": "password",
        "label": "Password",
        "placeholder": "Enter your password"
      },
      {
        "type": "hidden",
        "name": "userDetail",
        "value": "some_secret_detail"
      },
      {
        "type": "radio",
        "title": "What do you identify as:",
        "name": "Gender",
        "options": [
          {
            "label": "Male",
            "value": "male"
          },
          {
            "label": "Female",
            "value": "female"
          },
          {
            "label": "Other",
            "value": "other"
          }
        ]
      },
      {
        "type": "checkbox",
        "title": "Choose your Music Type:",
        "name": "music_type",
        "options": [
          {
            "label": "Metal",
            "value": "metal"
          },
          {
            "label": "Pop",
            "value": "pop"
          },
          {
            "label": "Blues",
            "value": "blues"
          },
          {
            "label": "Folk",
            "value": "folk"
          }
        ]
      },
      {
        "type": "submit",
        "label": "Submit",
        "requestType": "json",
        "formAction": "<URL>",
        "message": "optional- this message will be used as acknowledgement text when user clicks the button"
      }
    ]
  }
}

Note: The value of formAction need to be replaced with a valid URL.

// If requestType parameter is not passed, it will submit the formData with
// contentType application/x-www-form-urlencoded.
// If requestType parameter is json/postBackToBotPlatform the content type will be application/json.

// The form data will be extracted as below,

{
  Name: "Jithin", // "Name" is the input label and "Jithin" is the input value
  Password :"password123", // "Password" is the input label and "password123" is the input value
  userDetail: "some_secret_key", // Hidden field where "userDetail" is the name and "some_secret_key" is the value,
  Gender: "Male", //Radio button where "Gender" is the name of the radio button and "Male" is the value of the checked radio option,
  music_type: ["Metal","folk"] //"Genre" is the name of the checkbox field and the value is an array of the selected checkbox options


}

If the requestType parameter is postBackToBotPlatform, Kommunicate will send form data back to your bot. You need to enable the fulfillment from Dialogflow console to access this data. Once it is enabled, you can access this data from the fulfillment code under originalDetectIntentRequest property. Below is the sample data your fulfillment will receive.

{
 ...
 "originalDetectIntentRequest": {
   "payload": {
     "formData": {
       "Name": "Jithin",
       "Age": "25"
     },
     "applicationId": "102797803a1e00dccfa83eaf700f2b28a",
     "attachments": [],
     "botId": "bot-cf6gk",
     "groupId": "341144",
     "messageSource": "1"
   }
 }
 ...
}