Share via

Implement channel-specific functionality with the Bot Connector API

  • Article

Some channels provide features that can't 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

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:

{
    "type": "ActivityTypes.Message",
    "locale": "en-Us",
    "channelID": "email",
    "fromName": { "id": "mybot@mydomain.com", "name": "My bot"},
    "recipientName": { "id": "joe@otherdomain.com", "name": "Joe Doe"},
    "conversation": { "id": "123123123123", "topic": "awesome chat" },
    "channelData":
    {
        "htmlBody": "<html><body style = \"font-family: Calibri; font-size: 11pt;\" >This is more than awesome.</body></html>",
        "importance": "high",
        "ccRecipients": "Yasemin@adatum.com;Temel@adventure-works.com",
    }
}

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>",
    "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 (such as, REGULAR, SILENT_PUSH, or 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
  • banChatMember
  • sendAudio
  • sendChatAction
  • sendContact
  • sendDocument
  • sendLocation
  • sendMessage
  • sendPhoto
  • sendSticker
  • sendVenue
  • sendVideo
  • sendVoice
  • unbanChatMember

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 don't 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"
        }
    }
]

Additional resources