Implement channel-specific functionality with the Bot Connector API

Article
12/13/2017

APPLIES TO: SDK v3

Some channels provide features that cannot be implemented by using only message text and attachments. To implement channel-specific functionality, you can pass native metadata to a channel in the [Activity[]] object's channelData property. For example, your bot can use the channelData property to instruct Telegram to send a sticker or to instruct Office365 to send an email.

This article describes how to use a message activity's channelData property to implement this channel-specific functionality:

Channel	Functionality
Email	Send and receive an email that contains body, subject, and importance metadata
Slack	Send full fidelity Slack messages
Facebook	Send Facebook notifications natively
Telegram	Perform Telegram-specific actions, such as sharing a voice memo or a sticker
Kik	Send and receive native Kik messages

Note

The value of an Activity object's channelData property is a JSON object. The structure of the JSON object will vary according to the channel and the functionality being implemented, as described below.

Create a custom Email message

To create an email message, set the Activity object's channelData property to a JSON object that contains these properties:

Property	Description
htmlBody	The HTML to use for the body of the message.
subject	The subject to use for the message.
importance	The importance flag to use for the message: `low`, `normal`, or `high`.
toRecipients	A semicolon (;) delimited string of email addresses to add to the message's To field.
ccRecipients	A semicolon (;) delimited string of email addresses to add to the message's Cc (carbon copy) field.
bccRecipients	A semicolon (;) delimited string of email addresses to add to the message's Bcc (blind carbon copy) field.

This snippet shows an example of the channelData property for a custom email message.

"channelData":
{
    "htmlBody": "<html><body style = /"font-family: Calibri; font-size: 11pt;/" >This is more than awesome.</body></html>",
    "subject": "Super awesome message subject",
    "importance": "high",
    "ccRecipients": "Yasemin@adatum.com;Temel@adventure-works.com"
}

Create a full-fidelity Slack message

To create a full-fidelity Slack message, set the Activity object's channelData property to a JSON object that specifies Slack messages, Slack attachments, and/or Slack buttons.

Note

To support buttons in Slack messages, you must enable Interactive Messages when you connect your bot to the Slack channel.

This snippet shows an example of the channelData property for a custom Slack message.

"channelData": {
   "text": "Now back in stock! :tada:",
   "attachments": [
        {
            "title": "The Further Adventures of Slackbot",
            "author_name": "Stanford S. Strickland",
            "author_icon": "https://api.slack.com/img/api/homepage_custom_integrations-2x.png",
            "image_url": "http://i.imgur.com/OJkaVOI.jpg?1"
        },
        {
            "fields": [
                {
                    "title": "Volume",
                    "value": "1",
                    "short": true
                },
                {
                    "title": "Issue",
                    "value": "3",
                    "short": true
                }
            ]
        },
        {
            "title": "Synopsis",
            "text": "After @episod pushed exciting changes to a devious new branch back in Issue 1, Slackbot notifies @don about an unexpected deploy..."
        },
        {
            "fallback": "Would you recommend it to customers?",
            "title": "Would you recommend it to customers?",
            "callback_id": "comic_1234_xyz",
            "color": "#3AA3E3",
            "attachment_type": "default",
            "actions": [
                {
                    "name": "recommend",
                    "text": "Recommend",
                    "type": "button",
                    "value": "recommend"
                },
                {
                    "name": "no",
                    "text": "No",
                    "type": "button",
                    "value": "bad"
                }
            ]
        }
    ]
}

When a user clicks a button within a Slack message, your bot will receive a response message in which the channelData property is populated with a payload JSON object. The payload object specifies contents of the original message, identifies the button that was clicked, and identifies the user who clicked the button.

This snippet shows an example of the channelData property in the message that a bot receives when a user clicks a button in the Slack message.

"channelData": {
    "payload": {
        "actions": [
            {
                "name": "recommend",
                "value": "yes"
            }
        ],
        . . .
        "original_message": "{…}",
        "response_url": "https://hooks.slack.com/actions/..."
    }
}

Your bot can reply to this message in the normal manner, or it can post its response directly to the endpoint that is specified by the payload object's response_url property. For information about when and how to post a response to the response_url, see Slack Buttons.

Create a Facebook notification

To create a Facebook notification, set the Activity object's channelData property to a JSON object that specifies these properties:

Property	Description
notification_type	The type of notification (e.g., REGULAR, SILENT_PUSH, NO_PUSH).
attachment	An attachment that specifies an image, video, or other multimedia type, or a templated attachment such as a receipt.

Note

For details about format and contents of the notification_type property and attachment property, see the Facebook API documentation.

This snippet shows an example of the channelData property for a Facebook receipt attachment.

"channelData": {
    "notification_type": "NO_PUSH",
    "attachment": {
        "type": "template"
        "payload": {
            "template_type": "receipt",
            . . .
        }
    }
}

Create a Telegram message

To create a message that implements Telegram-specific actions, such as sharing a voice memo or a sticker, set the Activity object's channelData property to a JSON object that specifies these properties:

Property	Description
method	The Telegram Bot API method to call.
parameters	The parameters of the specified method.

These Telegram methods are supported:

answerInlineQuery
editMessageCaption
editMessageReplyMarkup
editMessageText
forwardMessage
kickChatMember
sendAudio
sendChatAction
sendContact
sendDocument
sendLocation
sendMessage
sendPhoto
sendSticker
sendVenue
sendVideo
sendVoice
unbanChateMember

For details about these Telegram methods and their parameters, see the Telegram Bot API documentation.

Note

The chat_id parameter is common to all Telegram methods. If you do not specify chat_id as a parameter, the framework will provide the ID for you.
Instead of passing file contents inline, specify the file using a URL and media type as shown in the example below.
Within each message that your bot receives from the Telegram channel, the channelData property will include the message that your bot sent previously.

This snippet shows an example of a channelData property that specifies a single Telegram method.

"channelData": {
    "method": "sendSticker",
    "parameters": {
        "sticker": {
            "url": "https://domain.com/path/gif",
            "mediaType": "image/gif",
        }
    }
}

This snippet shows an example of a channelData property that specifies an array of Telegram methods.

"channelData": [
    {
        "method": "sendSticker",
        "parameters": {
            "sticker": {
                "url": "https://domain.com/path/gif",
                "mediaType": "image/gif",
            }
        }
    },
    {
        "method": "sendMessage",
        "parameters": {
            "text": "<b>This message is HTML formatted.</b>",
            "parse_mode": "HTML"
        }
    }
]

Create a native Kik message

To create a native Kik message, set the Activity object's channelData property to a JSON object that specifies this property:

Property	Description
messages	An array of Kik messages. For details about Kik message format, see Kik Message Formats.

This snippet shows an example of the channelData property for a native Kik message.

"channelData": {
    "messages": [
        {
            "chatId": "c6dd8165…",
            "type": "link",
            "to": "kikhandle",
            "title": "My Webpage",
            "text": "Some text to display",
            "url": "http://botframework.com",
            "picUrl": "http://lorempixel.com/400/200/",
            "attribution": {
                "name": "My App",
                "iconUrl": "http://lorempixel.com/50/50/"
            },
            "noForward": true,
            "kikJsData": {
                    "key": "value"
                }
        }
    ]
}

Share via

Implement channel-specific functionality with the Bot Connector API

Create a custom Email message

Create a full-fidelity Slack message

Create a Facebook notification

Create a Telegram message

Create a native Kik message

Additional resources

Additional resources