Configuring Channels

If you want to be able to take advantage of special features or concepts for a channel we provide a way for you to send native metadata to that channel giving you much deeper control over how your bot interacts on a channel. The way you do this is to pass extra properties via the ChannelData property.

>NOTE: You do not need to use this feature unless you feel the need to access functionality not provided by the normal Activity.

Custom Email Messages

The Email channel optionally supports the ability to send custom properties to take advantage of what you can do with email.

When you receive a message via email the channelData will have metadata from the source message.

When you reply to a message via the email channel you can specify the following 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/High)

Example Message:

1 {
2  "type": "message",
3  "locale": "en-Us",
4  "channelID":"email",
5  "from": { "id":"mybot@gmail.com", "name":"My bot"},
6  "recipient": { "id":"joe@gmail.com", "name":"Joe Doe"},
7  "conversation": { "id":"123123123123", "topic":"awesome chat" },
8  "channelData":
9  {
10  "htmlBody" : "<html><body style = \"font-family: Calibri; font-size: 11pt;\" >This is more than awesome</body></html>",
11  "subject":"Super awesome message subject",
12  "importance":"high"
13  }
14 }

Custom Slack Messages

Slack supports the ability to create full fidelity slack messages. The slack channel allows bots to pass custom Slack messages via the ChannelData field. Custom messages passed via ChannelData will be posted directly to Slack via their chat.postMessage api.

See Slack Messages for a description of the Slack message format

See Slack Attachments for a description of Slack attachments

Example outgoing message with custom Slack message in ChannelData:

1 {
2  "type": "message",
3  "locale": "en-Us",
4  "channelId":"slack",
5  "conversation": { "id":"123123123123", "topic":"awesome chat" },
6  "from": { "id":"12345", "name":"My Bot"},
7  "recipient": { "id":"67890", "name":"Joe Doe"},
8  "channelData":
9  {
10  "text": "Now back in stock! :tada:",
11  "attachments": [
12  {
13  "title": "The Further Adventures of Slackbot",
14  "author_name": "Stanford S. Strickland",
15  "author_icon": "https://api.slack.com/img/api/homepage_custom_integrations-2x.png",
16  "image_url": "http://i.imgur.com/OJkaVOI.jpg?1"
17  },
18  {
19  "fields": [
20  {
21  "title": "Volume",
22  "value": "1",
23  "short": true
24  },
25  {
26  "title": "Issue",
27  "value": "3",
28  "short": true
29  }
30  ]
31  },
32  {
33  "title": "Synopsis",
34  "text": "After @episod pushed exciting changes to a devious new branch back in Issue 1, Slackbot notifies @don about an unexpected deploy..."
35  },
36  {
37  "fallback": "Would you recommend it to customers?",
38  "title": "Would you recommend it to customers?",
39  "callback_id": "comic_1234_xyz",
40  "color": "#3AA3E3",
41  "attachment_type": "default",
42  "actions": [
43  {
44  "name": "recommend",
45  "text": "Recommend",
46  "type": "button",
47  "value": "recommend"
48  },
49  {
50  "name": "no",
51  "text": "No",
52  "type": "button",
53  "value": "bad"
54  }
55  ]
56  }
57  ]
58  },
59  ...
60 }

When a user clicks a button in Slack, a message will be sent to your bot with ChannelData containing a Payload corresponding to the message action. The payload contains the original message as well as information about which button was clicked and who clicked it. Your bot can then take whatever action is necessary in response to the button click, including modifying the original message and posting to directly back to Slack via the response_url that's included in the payload.

See Slack Buttons for a description of interactive Slack messages

To support Slack buttons, you must follow the instructions to enable Interactive Messages when configuring your bot on the Slack channel.

Example incoming button click message:

1 {
2  "type": "message",
3  "serviceUrl": "https://slack.botframework.com",
4  "channelId": "slack",
5  "from": {...},
6  "conversation": {...},
7  "recipient": {...},
8  "text": "recommend",
9  "entities": [...],
10  "channelData": {
11  "Payload": {
12  "actions": [
13  {
14  "name": "recommend",
15  "value": "recommend"
16  }
17  ],
18  "callback_id": "comic_1234_xyz",
19  "team": {...},
20  "channel": {...},
21  "user": {...},
22  "attachment_id": "3",
23  "token": "...",
24  "original_message": {
25  "text": "New comic book alert!\n",
26  "username": "TestBot-V3 (Prod)",
27  "bot_id": "B1Q3CDE1M",
28  "attachments": [
29  {
30  "fallback": "332x508px image",
31  "image_url": "http://i.imgur.com/OJkaVOI.jpg?1",
32  "image_width": 332,
33  "image_height": 508,
34  "image_bytes": 60672,
35  "author_name": "Stanford S. Strickland",
36  "title": "The Further Adventures of Slackbot",
37  "id": 1,
38  "author_icon": "https://api.slack.com/img/api/homepage_custom_integrations-2x.png",
39  "fields": [
40  {
41  "title": "Volume",
42  "value": "1",
43  "short": true
44  },
45  {
46  "title": "Issue",
47  "value": "3",
48  "short": true
49  }
50  ]
51  },
52  {
53  "text": "After @episod pushed exciting changes to a devious new branch back in Issue 1, Slackbot notifies @don about an unexpected deploy...",
54  "title": "Synopsis",
55  "id": 2,
56  "fallback": "NO FALLBACK DEFINED"
57  },
58  {
59  "callback_id": "comic_1234_xyz",
60  "fallback": "Would you recommend it to customers?",
61  "title": "Would you recommend it to customers?",
62  "id": 3,
63  "color": "3AA3E3",
64  "actions": [
65  {
66  "id": "1",
67  "name": "recommend",
68  "text": "Recommend",
69  "type": "button",
70  "value": "recommend"
71  },
72  {
73  "id": "2",
74  "name": "no",
75  "text": "No",
76  "type": "button",
77  "value": "bad"
78  }
79  ]
80  }
81  ],
82  "type": "message",
83  "subtype": "bot_message",
84  },
85  "response_url": "https://hooks.slack.com/actions/..."
86  }
87  }
88 }

Custom Facebook Messages

The Facebook adapter supports sending full attachments via the channelData field. This allows you to do anything natively that Facebook supports via the attachment schema, such as receipt.

Property Description
* notification_type* Push notification type: REGULAR, SILENT_PUSH, NO_PUSH
* attachment* A Facebook formatted attachment * SeeFacebook Send API Reference*

Example Message:

1 {
2  "type": "message",
3  "locale": "en-Us",
4  "text": "This is a test",
5  "channelID":"facebook",
6  "conversation": { "id":"123123123123", "topic":"awesome chat" },
7  "from": { "id":"12345", "name":"My Bot"},
8  "recipient": { "id":"67890", "name":"Joe Doe"},
9  "channelData":
10  {
11  "notification_type" : "NO_PUSH",
12  "attachment":
13  {
14  "type":"template",
15  "payload":
16  {
17  "template_type":"receipt",
18  "recipient_name":"Stephane Crozatier",
19  "order_number":"12345678902",
20  "currency":"USD",
21  "payment_method":"Visa 2345",
22  "order_url":"http://petersapparel.parseapp.com/order?order_id=123456",
23  "timestamp":"1428444852",
24  "elements":
25  [
26  {
27  "title":"Classic White T-Shirt",
28  "subtitle":"100% Soft and Luxurious Cotton",
29  "quantity":2,
30  "price":50,
31  "currency":"USD",
32  "image_url":"http://petersapparel.parseapp.com/img/whiteshirt.png"
33  },
34  {
35  "title":"Classic Gray T-Shirt",
36  "subtitle":"100% Soft and Luxurious Cotton",
37  "quantity":1,
38  "price":25,
39  "currency":"USD",
40  "image_url":"http://petersapparel.parseapp.com/img/grayshirt.png"
41  }
42  ],
43  "address":
44  {
45  "street_1":"1 Hacker Way",
46  "street_2":"",
47  "city":"Menlo Park",
48  "postal_code":"94025",
49  "state":"CA",
50  "country":"US"
51  },
52  "summary":
53  {
54  "subtotal":75.00,
55  "shipping_cost":4.95,
56  "total_tax":6.19,
57  "total_cost":56.14
58  },
59  "adjustments":
60  [
61  {
62  "name":"New Customer Discount",
63  "amount":20
64  },
65  {
66  "name":"$10 Off Coupon",
67  "amount":10
68  }
69  ]
70  }
71  }
72  }
73 }

Custom Telegram Messages

The Telegram channel supports calling Telegram Bot API methods via the channelData field. This allows your bot to perform Telegram-specific actions, such as sharing a voice memo, or a sticker.

Property Description
method The Telegram Bot API method to call. See below for supported methods.
parameters Associative array containing method parameters. Parameters are method-specific.

>See the Telegram Bot API Documentation for a description of all available methods, parameters, and types.

Special Notes:

  1. The chat_id parameter is common to all Telegram methods.If not provided, the framework will fill in this value for you.
  2. The Telegram channel expresses Telegram's InputFile type differently than the way it appears in the Telegram Bot API. Rather than sending the file contents, your bot should pass the file's url and mediaType. This is shown in the example message below.
  3. When your bot receives a Connector message from the Telegram channel, the original Telegram message will be present in the channelData field.

Example Message:

1 {
2  "type": "message",
3  "locale": "en-Us",
4  "channelID":"telegram",
5  "from": { "id":"12345", "name":"My Bot"},
6  "recipient": { "id":"67890"}, "name":"Joe Doe"},
7  "conversation": { "id":"123123123123", "topic":"awesome chat" },
8  "channelData":
9  {
10  "method": "sendSticker",
11  "parameters":
12  {
13  "sticker":
14  {
15  "url": "https://upload.wikimedia.org/wikipedia/commons/3/33/LittleCarron.gif",
16  "mediaType": "image/gif"
17  }
18  }
19  }
20 }

You may pass multiple Telegram methods as an array:

1 {
2  "type": "message",
3  "locale": "en-Us",
4  "channelID":"telegram",
5  "from": { "id":"12345", "name":"My Bot"},
6  "recipient": { "id":"67890"}, "name":"Joe Doe"},
7  "conversation": { "id":"123123123123", "topic":"awesome chat" },
8  "channelData":
9  [
10  {
11  "method": "sendSticker",
12  "parameters":
13  {
14  "sticker":
15  {
16  "url": "http://www.gstatic.com/webp/gallery/1.webp",
17  "mediaType": "image/webp"
18  }
19  }
20  },
21  {
22  "method": "sendMessage",
23  "parameters":
24  {
25  "text": "<b>This message is HTML-formatted.</b>",
26  "parse_mode": "HTML"
27  }
28  }
29  ]
30 }

Supported Methods:

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

Custom Kik Messages

The Kik adapter supports sending native Kik messages via the channelData field. This allows you to do anything natively that Kik supports.

Property Description
messages An array of messages. See Kik Messages

Example Message:

1 {
2  "type": "message",
3  "locale": "en-Us",
4  "channelID":"kik",
5  "from": { "id":"12345", "name":"My Bot"},
6  "recipient": { "id":"67890"}, "name":"Joe Doe"},
7  "conversation": { "id":"123123123123", "topic":"awesome chat" },
8  "channelData": {
9  "messages": [
10  {
11  "chatId": "c6dd81652051b8f02796e152422cce678a40d0fb6ad83acd8f91cae71d12f1e0",
12  "type": "link",
13  "to": "kikhandle",
14  "title": "My Webpage",
15  "text": "Some text to display",
16  "url": "http://botframework.com",
17  "picUrl": "http://lorempixel.com/400/200/",
18  "attribution": {
19  "name": "My App",
20  "iconUrl": "http://lorempixel.com/50/50/"
21  },
22  "noForward": true,
23  "kikJsData": {
24  "key": "value"
25  }
26  }
27  ]
28  }
29 }