In addition to text messages and images, Brand Messenger supports sending structured messages to your users. Structured messages empower brands to deliver an elevated user experience with each conversation.

Providing media and interactive elements to users in the context of a conversation provides a number of benefits, including:

Enhanced information gathering
Uplifted customer experience
Product discovery and feature highlights
In this guide, we will examine how you can use the Brand Messenger API to leverage structured messages to their full potential.

API Reference

The following API endpoints enable you to register bots and respond to conversations using a bot through the Khoros Care API.

📘
Throughout this document, snippets featured in the API examples assume that you are using the Khoros Care API's respond to the conversation from bot via API endpoint.
The code featured in the examples in this guide should be placed in the payload of that call using the raw payload (passthrough) method.

Here's an example of a valid API call:

{
    "coordinate": {},
    "author": {},
    "type": "message",
    <payload>
}

Action Buttons

There are three basic types of action buttons supported in Brand Messenger.

Link Buttons
Suggested Reply Buttons
Postback Buttons

Link Buttons

Link buttons allow you to send a call to action that opens a URL when tapped or clicked. You can configure the buttons with any valid URL. This is a great way to send links to web pages, deep-link into apps (Android and iOS), etc.

You can use the API to refine the behavior of the link button.

All buttons in Brand Messenger and Brand Messenger messages are specified in the actions array in the payload of the send message function.

{
    "linkButtons": {
        "linkButtonList": [
            {
                "name": "Financial services",
                "url": "https://khoros.com/industry/financial-services",
                "openInNewTab": false
            },
            {
                "name": "Travel and Hospitality",
                "url": "www.khoros.com/industry/travel-hospitality",
                "openInNewTab": true
            },
            {
                "name": "Retail & Distribution",
                "url": "https://khoros.com/industry/retail-distribution",
                "openInNewTab": true
            }
        ]
    }
}

The linkButtons array has the following fields:

url: The URL you want the button to direct the user to.
name: The forward-facing name you want to label the button.
openInNewTab: When the value is true, the url opens in a new browser tab.

Suggested Reply Buttons

Suggested Reply buttons make walking a user through a predefined flow simple and easy. It gives them simple buttons to select which determine the course of action the conversation will take.

To the user, it's a click of a button to relay information such as the purpose of the contact. The agent receives a pre-written reply based on the button selected by the user.

This further makes the configuration of bots easier by establishing predictable responses from the user that the bot can react to.

Each suggestedReply object has two fields

title: The forward-facing name you want to label the button.
message: The message text that is sent from the user to the agent when any button is selected

The message is delivered as a normal message, appearing in any business system integrations, and delivered to webhooks subscribed to the message:appUser event.

The API grants you control over the presentation of reply buttons. For example, you can configure an icon to appear in the reply button:

"text": "Please select what you need help with",
    "suggestedReplies": [
        {
            "title": "SIM plans",
            "message": "Need information about SIM plans"
        },
        {
            "title": "Data packs",
            "message": "Need information about data packs"
        },
        {
            "title": "Get a new SIM",
            "message": "Get a new SIM"
        }
    ]

Postback Buttons

Postback buttons, like Reply buttons, include an associated payload. This payload is used to trigger webhooks that are actively listening to the postback trigger. This feature is especially valuable in the building of bot.

Here are some ways Postback buttons differ from Reply buttons:

Postback buttons are also multi-use, enabling the user to repeatedly select them throughout the conversation.
Postback selections do not appear in the conversation history.
Postbacks utilize the postback webhook event, and not the message:appUser event.

You can use Postbacks in combination with other button types using the API. For example:

{
    "role": "appMaker",
    "type": "text",
    "actions": [
        {
            "type": "postback",
            "text": "Postback Button Label",
            "payload": "PAYLOAD_HERE"
        },
        {
            "type": "link",
            "text": "Link Button Label",
            "payload": "http://url.button.com"
        }
    ]
}

Cards

Brand Messenger gives you the ability to create a rich horizontally-scrollable experience for users including items, each containing the following:

Header
Image (optional)
Overlay text (optional)
Card information section
Title
Title extension (optional)
Subtitle
Description (use \n to break the line.)
Card footer may contain a list of buttons, it can be:
- Link Button
- Suggested Replies

Here is an example of a Cards implemented through Brand Messenger.

"text": "Here is a movie recommendation for you",
    "genericCards": [
        {
            "title": "Batman",
            "subtitle": "2008",
            "headerOverlayText": "Buy now",
            "headerImageUrl": "https://images/2020/07/31/Pictures/_e30b6ad4-d312-11ea-9eb6-4e4101534b74.jpg",
            "description": "Dark, complex, and unforgettable, The Dark Knight succeeds as a richly thrilling crime saga.",
            "titleExt": "The Dark Knight",
            "buttons": [
                {
                    "name": "View Reviews",
                    "type": "LINK_BUTTON",
                    "payload": "https://www.google.com/search?q=batmanReviews"
                },
                {
                    "name": "Enquire buying options",
                    "type": "SUGGESTED_REPLY",
                    "payload": "movie"
                },
                {
                    "type": "SUGGESTED_REPLY",
                    "name": "Suggest something else",
                    "payload": "Suggest something else"
                }
            ]
        }
    ]

You can also send a set of cards to create a horizontally scrollable experience

"text": "Gift cards you can get",
    "genericCards": [
        {
            "title": "25$ gift card",
            "subtitle": "1 year validity",
            "headerImageUrl": "https://images/rf/image_size_630x354/HT/p2/2020/07/31/Pictures/_e30b6ad4-d312-11ea-9eb6-4e4101534b74.jpg",
            "buttons": [
                {
                    "name": "See more",
                    "type": "LINK_BUTTON",
                    "payload": "https://www.abc.com/giftcards/25"
                },
                {
                    "name": "Buy",
                    "type": "SUGGESTED_REPLY",
                    "payload": "buy"
                }
            ]
        },
        {
            "title": "50$ gift card",
            "subtitle": "1 year validity",
            "headerImageUrl": "https://images/rf/image_size_630x354/HT/p2/2020/07/31/Pictures/_e30b6ad4-d312-11ea-9eb6-4e4101534b74.jpg",
            "buttons": [
                {
                    "name": "See more",
                    "type": "LINK_BUTTON",
                    "payload": "https://www.abc.com/giftcards/50"
                },
                {
                    "name": "Buy",
                    "type": "SUGGESTED_REPLY",
                    "payload": "buy"
                }
            ]
        },
        {
            "title": "75$ gift card",
            "subtitle": "1 year validity",
            "headerImageUrl": "https://images/rf/image_size_630x354/HT/p2/2020/07/31/Pictures/_e30b6ad4-d312-11ea-9eb6-4e4101534b74.jpg",
            "buttons": [
                {
                    "name": "See more",
                    "type": "LINK_BUTTON",
                    "payload": "https://www.abc.com/giftcards/75"
                },
                {
                    "name": "Buy",
                    "type": "SUGGESTED_REPLY",
                    "payload": "buy"
                }
            ]
        }
    ]