In addition to text messages and images, Brand Messenger Legacy 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 Legacy 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 Method 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": "{\"role\": \"appMaker\",\"type\": \"text\",\"actions\": [{\"type\": \"link\",\"text\": \"Learn more\",\"uri\": \"https://www.example.com/en/index.html\"}]}"
}

Shorthand

When you are responding to a user using a bot, shorthand can be passed directly into the payload. The shorthand will automatically render in the chat window.

In the example below, we are assuming the bot is interacting with the Automation Framework on a new message.

const baseUrl = 'https://example.response.lithium.com'
const { author, coordinate } = req.body;
const shorthand = '%[Click here](postback:clicked)';
 
const token = <token generated when you register the bot>;
const headers = {
            headers: {
                "Authorization": "Bearer " + token
            }
        };
  
const payload = { 
                coordinate,
                "type":"message",
                author,
                "text": `${shorthand}`
            };
const respondUrl = `${baseUrl}/bots/v3/respond`;
await axios.post(respondUrl, payload, headers);

Elements

Below is a quick reference to the different shorthand elements available in the Brand Messenger Legacy.

Element	Syntax	Example
Link Button	`%[]()`	`%[Button label](http://anyurl.com)`
Reply Button	`%[](reply:)`	`%[Button label](reply:PAYLOAD)`
Postback Button	`%[](postback:)`	`%[Button label ](postback:PAYLOAD)`
Location Request Button	`%[](location)`	`%[Button label](location)`
Payment Button	`$[]()`	`$[Button label here](25.00)`
Image	`![]()`	`![](http://url-of.the/image.jpg)`
Template Message	`%((template:))% or %{{template:}}%`	`%((template:TEMPLATE_NAME))%`

Template Messages

Template messages are a great way to create "canned" responses which provide a lot of information that Agents frequently use when interacting with users. When it comes to structured messages, they are especially useful as they make initiating them easy for both human Agents and bots, alike.

Here is a breakdown of the template message arguments available:

Argument	Required?	Description
role	Yes	The role of the individual posting the message. Can be either `appUser` or `appMaker`.
type	Yes	The type of the message being posted. Can be `text`, `image`, `file`, `carousel`, `location` or `form`.
name	No	The display name of the message author. Messages with role `appUser` will default to a friendly name based on the user’s `givenName` and `surname`. Messages with role `appMaker` have no default name.
email	No	The email address of the message author. This field is typically used to identify an app maker in order to render the avatar in the app user client. If the email of the account is used, the configured profile avatar will be used.
avatarUrl	No	The URL of the desired message avatar image. This field will override any avatar chosen via the email parameter.
destination	No	The channel where you want your message delivered to. This only works for messages with role `appMaker`.
metadata	No	Flat object containing any custom properties associated with the message. If you are developing your own messaging client you can use this field to render custom message types.
payload	No	The payload of a reply action, if applicable.

Template Response

When responding to the author from the bot, you can pass the template name into the payload via shorthand. This adds a step to the process where you must create a template to represent the chat message.

In the NodeJS example below, we are assuming the bot is interacting with the Automation Framework on a new message.

const baseUrl = 'https://example.response.lithium.com'
const { author, coordinate } = req.body;
  
// Create a template
const structuredMessageJson = {
            "text":"Search results",
            "role": "appMaker",
            "type": "text",
            "actions": [
                {
                    "type": "webview",
                    "text": "Search results",
                    "uri": "https://www.example.com/en/index.html",
                    "fallback": "https://www.example.com/de/index.html"
                }
            ]
        };
const name =  Math.random().toString(36).substring(2, 15) + Math.random().toString(36).substring(2, 15);
let template = { name, message: structuredMessageJson};
const appId = "<found in widget code>";
const BASE_URL = 'https://api.smooch.io';
const url = `${BASE_URL}/v1.1/apps/${appId}/templates`;
 
// THIS CAN NOT BE FOUND IN ADMIN. KEEP THIS SAFE
const keyId = "PRIVATE_KEY";
const keySecret = "SECRET";
 
 
const TOKEN = Buffer.from((keyId + ':' + keySecret)).toString('base64');
let headers = {
    "Authorization": "Basic " + TOKEN
};
await axios.post(url, template, { headers });
 
const token = <token generated when you register the bot>;
const headers = {
            headers: {
                "Authorization": "Bearer " + token
            }
        };
  
const payload = { 
                coordinate,
                "type":"message",
                author,
                "text": `%((template:${template.name}))%`
            };
const respondUrl = `${baseUrl}/bots/v3/respond`;
await axios.post(respondUrl, payload, headers);

Here is the result:

Action Buttons

Action buttons assist you with guiding the user experience throughout the conversation. A button appearing in the context of a conversation acts as a call-to-action. It is a great way to gather and share information and direct users to their desired destination.

Here are some examples to help you get started with buttons.

Here is a simple button that will post back to the page with a response.

%[Button text ](postback:<text>)

This is a button that redirects to a webpage.

%[external website](https://www.example.com)

You can also render multiple buttons.

%[button1](reply:1)
%[button2](reply:2)
%[button3](reply:3)

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.

Shorthand Method

Sending a link button with messaging shorthand is easy. Simply add shorthand based on the following example to your message:

%[Button Label](http://url.button.com)

Brand Messenger Legacy will convert the shorthand into a link button.

API Method

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

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

{
            "role": "appMaker",
            "type": "text",
            "actions": [
                    {
                        "type": "link",
                        "text": "Learn more",
                        "uri": "https://www.example.com/en/index.html"
                    }
            ]
}

Webview Buttons

Webview buttons allow you to send conversation extensions to create custom experiences over the conversation.

To the user, a tap of the button seamlessly opens an interactive experience. This experience guides them through a process such as booking a room in a hotel, choosing options for a new vehicle, etc.

To send a Webview button, use the Brand Messenger Legacy API. Here's an example:

{
            "text":"Search results",
            "role": "appMaker",
            "type": "text",
            "actions": [
                {
                    "type": "webview",
                    "text": "Search results",
                    "uri": "https://www.example.com/en/index.html",
                    "fallback": "https://www.example.com/de/index.html"
                }
            ]
}

📘
If a user is messaging via Modern Chat in an https page, the webview URI must also be https or it will fail to load.

Reply Buttons

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 the 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 reply button has an associated payload, which identifies the intent of the action. When the user answers with one of the suggested replies, this payload is included as part of the message object. The message is delivered as a normal message, appearing in any business system integrations, and delivered to webhooks subscribed to the message:appUser event.

Shorthand Method

You can send a reply button with the following syntax:

%[Button label here](reply:PAYLOAD_HERE)

API Method

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

{
            "role": "appMaker",
            "type": "text",
            "actions": [
                    {
                        "type": "reply",
                        "text": "Tacos",
                        "iconUuri": "http://example.com/taco.png"
                        "payload": "TACOS"
                    },
                    {
                        "type": "reply",
                        "text": "Burritos",
                        "iconUrl": "http://example.com/burrito.png",
                        "payload": "BURRITOS"
                    }
            ]
}

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.

Shorthand Method

Here is the syntax used to create a Postback button using the shorthand method:

%[Button label here](postback:PAYLOAD_HERE)

API Method

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

Location Request Buttons

Location requests provide critical location context for when you need it most. They're frequently used in the areas of travel, transport, real estate, logistics, and beyond.

Location requests are natively supported on the Brand Messenger Legacy through the iOS, Android, and Modern Chat SDKs.

Partial support exists on other channels including LINE and SMS by sending the request in text format.

Shorthand Method

To request location from a user, you can use the following syntax:

%[Send location](location)

API Method

To utilize the API to make a location request, follow the example below.

{
        text: "What's your location?",
        role: 'appMaker',
        type: 'text',
        actions: [
            {
                text: 'Send Location',
                type: 'locationRequest'
            }
        ]
}

Carousel Messages

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

Text
Image
Message actions

Here is an example of a Carousel implemented through Brand Messenger Legacy.

{
            "role": "appMaker",
            "type": "carousel",
            "items": [
                {
                    "title": "Example Title",
                    "description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Quisque vestibulum purus condimentum.",
                    "mediaUrl": "https://via.placeholder.com/300/09f/fff.png",
                    "mediaType": "image/jpeg",
                    "actions": [
                        {
                            "type": "link",
                            "text": "Learn more",
                            "uri": "https://www.example.com/en/index.html"
                        },
                        {
                            "type": "webview",
                            "text": "Check availability",
                            "uri": "https://www.example.com/en/index.html",
                            "fallback": "https://www.google.com"
                        }
                    ]
                },
                {
                    "title": "Another Example",
                    "description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Quisque vestibulum purus condimentum.",
                    "mediaUrl": "https://via.placeholder.com/300/09f/fff.png",
                    "mediaType": "image/jpeg",
                    "actions": [
                        {
                            "type": "link",
                            "text": "Learn more",
                            "uri": "https://www.example.com/en/index.html"
                        },
                       {
                            "type": "webview",
                            "text": "Check availability",
                            "uri": "https://www.example.com/en/index.html",
                            "fallback": "https://www.google.com"
                        }
                    ]
                }
            ]
        }

Form Messages

Form messages are a great way to capture important data from your users within the context of a conversation. To put it simply, you display a form that your user can fill out within the chat window.

Forms can include text, email inputs, and dropdowns with specified options.

📘
Form messages are currently only available on Modern Chat.

Sending a form using the API is pretty straightforward. The fields in your form include a defined type, name, label, and placeholder. Dropdown fields include an options with each option including its own name and label.

Key	Required	Description
type	Yes	Specifies the type of field. Options are `text`, `email`, and `select`.
name	Yes	Specifies the name of the field. Each field name must be unique per form. Maximum length of 128 characters.
label	Yes	Specifies what label the field will be displayed with. Maximum length of 128 characters.
placeholder	No	Specifies the placeholder text of the field that will be rendered. Maximum length of 128 characters.
options	No	Select field only. Array of option objects that can be selected. The array is limited to 20 options.
minSize	No	Sets the minimum possible length of a response in a `text` field. Defaults to `1` of not specified.
maxSize	No	Sets the maximum possible length of a response in a `text` field. Defaults to `128` if not specified.

Here is an example:

{
    role: 'appMaker',
    type: 'form',
    fields: [
        {
            type: 'text',
            name: 'name',
            label: 'Name',
            placeholder: 'Enter your name...'
        },
        {
            type: 'email',
            name: 'email',
            label: 'Email',
            placeholder: 'Enter your email...'
        },
        {
            type: 'select',
            name: 'meal',
            label: 'Meal',
            placeholder: 'Choose your meal...',
            options: [
            {
                name: 'cookie',
                label: 'Cookie'
            },
            {
                name: 'pie',
                label: 'Pie'
            },
            {
                name: 'cake',
                label: 'Cake'
            }]
        }

    ]
}

Here is the result of the form created above: