Microsoft BotFrameworkHelper

To add media or cards, the Microsoft Bot Framework example connector looks for an output parameter msbotframework in the engine response. The value of that parameter is assumed to contain the media or card JSON as defined by Microsoft.

To make it easier to produce the JSON for common Microsoft Bot Framework attachments or cards when working in Teneo Studio, you can make use of BotFrameworkHelper, a .groovy file you can add to your solution. It contains example methods that allow you to easily produce the JSON needed for common bot framework attachments and cards. The source code is contained in the .groovy file itself, so you can easily extend it if desired. You can also find the file on Github.

Installation

Add the file BotFrameworkHelper.groovy to Resources in your solution and set the path to /script_lib

For more details on managing files in your solution, see Resource File Manager.

Attachments and cards

Image

To attach an image to an output, the following JSON needs to be added to the msbotframework output parameter:

{
    "name": "Example image",
    "contentType": "image/png",
    "contentUrl": "https://url.to/an/image.png"
}

See the Microsoft documentation for more details: Add a media attachment.

The following method can be used to produce the JSON:

BotFrameworkHelper.createImageJSON("https://url.to/image.png","Example image")

The arguments of the createImageJSON method are:

Argument	Type	Description
url	String	URL for the image. Supported protocols are: HTTP, HTTPS.
name	String	Name or alternative text for the image

Video

To attach a video to an output, the following JSON needs to be added to the msbotframework output parameter:

{
    "name": "Example video",
    "contentType": "video/mp4",
    "contentUrl": "https://url.to/an/video.mp4"
}

See the Microsoft documentation for more details: Add a media attachment.

When using the BotFrameworkHelper, the method 'createVideoJSON' can be used to produce the JSON above using the following Groovy code:

BotFrameworkHelper.createVideoJSON("https://url.to/video.mp4","Example video")

The arguments of the createVideoJSON method are:

Argument	Type	Description
url	String	URL for the video. Supported protocols are: HTTP, HTTPS.
name	String	Name or alternative text for the video

Suggested Actions (quick replies)

To attach suggested actions (also known as quick replies) to an output, the following JSON needs to be added to the msbotframework output parameter:

{
    "actions": [
        {
            "type": "imBack",
            "title": "Blue",
            "value": "Blue"
        },
        {
            "type": "imBack",
            "title": "Red",
            "value": "Red"
        },
        {
            "type": "imBack",
            "title": "Green",
            "value": "Green"
        }
    ]
}

See the Microsoft documentation for more details: Add suggested actions to messages.

When using the BotFrameworkHelper, the following Groovy code can be used to produce the JSON above:

def actions = []

actions << BotFrameworkHelper.createSuggestedActionButton("Red","Red")
actions << BotFrameworkHelper.createSuggestedActionButton("Green","Green")
actions << BotFrameworkHelper.createSuggestedActionButton("Blue","Blue")

suggestedActionsJSON = BotFrameworkHelper.createSuggestedActionsJSON(actions)

The createSuggestedActionButton method produces a map containing the details for a quick reply button. The method has the following arguments:

Argument	Type	Description
title	String	The title for the button, displayed to the user.
value	String	The value of the button, which is returned to Teneo when the user clicks the button

The buttons need to be added to a list. When that list is fed to the createSuggestedActionsJSON method, it will return the JSON that can be added to the output parameter msbotframework. The method takes the following argument:

Argument	Type	Description
actions	List	List of suggested action buttons

Note: Suggested actions are only supported in the tie-api-example-ms-bot-framework connector with version 1.1 or higher.

Hero Card

To attach a Hero Card to an output, JSON that looks similar to the code below needs to be added to the msbotframework output parameter:

{
    "contentType": "application/vnd.microsoft.card.hero",
    "content": {
        "title": "Card title",
        "subtitle": "Card subtitle",
        "text": "Card body text",
        "images": [
            {
                "url": "https://url.to/image.png",
                "alt": "Example image",
            }
        ],
        "buttons": [
            {
                "type": "postback",
                "title": "OK",
                "value": "User clicked ok"
            },
            {
                "type": "postback",
                "title": "Cancel",
                "value": "User clicked cancel"
            }
        ]
    }
}

See the Microsoft documentation for more details: Add a Hero card to a message.

When using the BotFrameworkHelper, the following Groovy code can be used to produce the JSON above:

// create hero card image
def myHeroCardImage = BotFrameworkHelper.createHeroCardImage("https://url.to/image.png","Example image")

// populate list of buttons to be shown on hero card
def myHeroCardButtons = []
myHeroCardButtons << BotFrameworkHelper.createPostbackButton("OK", "User clicked ok")
myHeroCardButtons << BotFrameworkHelper.createPostbackButton("Cancel", "User clicked cancel")

// create JSON for hero card
myHeroCard = BotFrameworkHelper.createHeroCardJSON("Card title","Card subtitle","Card body text", myHeroCardButtons, myHeroCardImage)

First the code creates a object for the hero card image using the createHeroCardImage method. These are the arguments:

Argument	Type	Description
url	String	URL for the image. Supported protocols are: HTTP, HTTPS.
alt	String	Alternative text for the image

Additionally, a list of hero card buttons is created. To create a hero card button, the method createPostbackButton button is used with the following arguments:

Argument	Type	Description
label	String	Label shown in the button
postbackValue	String	Value that should be posted back to Teneo when the user clicks/taps the button

Finally the method createHeroCardJSON that returns the JSON for the hero card is called. These are the arguments:

Argument	Type	Description
title	String	Title of the card. Maximum 2 lines; formatting not currently supported
subtitle	String	Subtitle of the card. Maximum 2 lines; formatting not currently supported
text	String	Text appears just below the subtitle; see Card formatting for formatting options
buttons	List	List of buttons applicable to the current card. Maximum 6. See method `createPostbackButton`
heroImage	List	List containing a single image. Image displayed at top of card. Aspect ratio 16:9. See method `createHeroCardImage`

Note: not all attachments or cards can be used on every channel supported by Microsoft. Since there is no real overview on the Microsoft site that shows you which channels support which attachments, the easiest way is to basically try it.