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
    • Form with Calendar Date Picker

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

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

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

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:

In the following Suggested Replies example, if you click the button "Yes" it will be showing the message "Cool! send me more." and if you click "No" it will be showing the message "Not at all".

These button titles and messages can be customized based on your requirement.

Suggested Replies

{
    "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"
        }]
    }
}

In addition, if you need you can use follow-up intents in Dialogflow to automatically set contexts for pairs of intents.

A follow-up intent is a child of its associated parent intent. When you create a follow-up intent, an output context is automatically added to the parent intent and an input context of the same name is added to the follow-up intent.

A follow-up intent is only matched when the parent intent is matched in the previous conversational turn. You can also create multiple levels of nested follow-up intents.

Dialogflow follow-up intent example:

Suggested Replies
Suggested Replies

In this example, The follow-up intents has been created for "Yes" and "No". When the buttons are clicked it will show the follow-up intent for that particular suggested reply.

Based on the use case and requirement, you can create follow-up texts, suggested replies, link buttons, etc.

Send custom data to bot platform via rich message response


{
    "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.

In the above example replyMetadata has the parameter "buttonClicked": "true", this will send the data to bot platform to confirm the end user has clicked on the button "NO". If you want to perform some actions if a user clicks on a certain button you can use this option.

It is useful in several requirements such as,

  • To know which button user has clicked.
  • To send the extra data when a user clicks on a button.

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.

List Template

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

Generic Card

Components of card template

A card template may contain below items:

Labeled Generic Card

  • 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.

Card Carousel Template

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.

Autosuggestions

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.

Form

parameterdescription
requestTypeIt 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.
replyTextIt 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"
   }
 }
 ...
}

Form validation

In order to restrict users from entering invalid data, add form field validation using regex.

Instructions

  1. Create the Regex according to your requirements.
  2. If your regex has forward-slash (/) at the beginning and ending please remove it.
  3. Use a backslash (the escape character) in Dialogflow to skip double quotes or any other character which is throwing error.
  4. If your Regex includes backslash, add one more backslash with it.

Below is the sample payload to validate an email input and to make the input field mandatory.

{
  "message": "Form",
  "platform": "kommunicate",
  "metadata": {
    "contentType": "300",
    "templateId": "12",
    "payload": [
      {
        "type": "text",
        "label": "Name",
        "placeholder": "Enter your name",
        "validation": {
          "regex": "[A-Za-z0-9]",
          "errorText": "Field is mandatory"
        }
      },
      {
        "type": "text",
        "label": "Email",
        "placeholder": "Enter your email",
        "validation": {
          "regex": "^(([^<>()\\[\\]\\.;:\\s@\"]+(\\.[^<>()[\\]\\.,;:\\s@\"]+)*)|(\".+\"))@((\\[[0-9]{1,3}\\.[0-9]{1,3}\\.[0-9]{1,3}\\.[0-9]{1,3}\\])|(([a-zA-Z\\-0-9]+\\.)+[a-zA-Z]{2,}))$",
          "errorText": "Invalid Email"
        }
      },
      {
        "type": "submit",
        "label": "Submit",
        "requestType": "json",
        "formAction": "https://reqres.in/api/users",
        "message": "Form was submitted succesfully!"
      }
    ]
  }
}
warning

Validation is only supported with input type "text".

Form with Calendar Date Picker

If your forms requires a calendar, then you can add it in the form template.

The Date Picker lets users quickly select dates from a collapsible calendar. It's perfect for order forms, reservation forms and booking forms, etc.

Form with Calendar Date Picker

Form with Calendar Date Picker

Payload for the calendar date picker

{
"payload": [
      {
        "type": "datetime-local",
        "label": "Date"
      }
    ]
}

Here is the sample JSON for the form with calendar date picker 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": "datetime-local",
        "label": "Date"
      },
      {
        "type": "radio",
        "title": "What do you identify as:",
        "name": "Gender",
        "options": [
          {
            "label": "Male",
            "value": "male"
          },
          {
            "label": "Female",
            "value": "female"
          },
          {
            "label": "Other",
            "value": "other"
          }
        ]
      },
      {
        "type": "submit",
        "label": "Submit",
        "requestType": "json",
        "formAction": "<URL>",
        "message": "optional- this message will be used as acknowledgement text when user clicks the button"
      }
    ]
  }
}
← How To UseAuthentication →