使用 Bot Connector API 來執行通道特定功能Implement channel-specific functionality with the Bot Connector API

某些通道所提供的功能,無法只透過訊息文字和附件來實作。Some channels provide features that cannot be implemented by using only message text and attachments. 若要實作通道特定的功能,您可以將原生中繼資料傳至 [Activity[]] 物件的 channelData 屬性中的通道。To implement channel-specific functionality, you can pass native metadata to a channel in the [Activity[]] object's channelData property. 例如,Bot 可以使用 channelData 屬性,指示 Telegram 傳送貼圖或指示 Office365 傳送電子郵件。For example, your bot can use the channelData property to instruct Telegram to send a sticker or to instruct Office365 to send an email.

此文章說明如何使用訊息活動的 channelData 屬性來實作此通道特定的功能: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
SlackSlack 傳送不失真的 Slack 訊息Send full fidelity Slack messages
FacebookFacebook 原生傳送 Facebook 通知Send Facebook notifications natively
TelegramTelegram 執行 Telegram 特定動作,例如共用語音備忘或貼圖Perform Telegram-specific actions, such as sharing a voice memo or a sticker
KikKik 傳送和接收原生 Kik 訊息Send and receive native Kik messages

注意

Activity 物件的 channelData 屬性值是一個 JSON 物件。The value of an Activity object's channelData property is a JSON object. JSON 物件的結構將根據正在實作的通道和功能而變化,如下所述。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

若要建立電子郵件訊息,請將 Activity 物件的 channelData 屬性設定為包含這些屬性的 JSON 物件:To create an email message, set the Activity object's channelData property to a JSON object that contains these properties:

屬性Property 描述Description
htmlBodyhtmlBody 用於訊息本文的 HTML。The HTML to use for the body of the message.
subjectsubject 用於訊息的主旨。The subject to use for the message.
importanceimportance 用於訊息的重要性旗標:lownormalhighThe importance flag to use for the message: low, normal, or high.
toRecipientstoRecipients 以分號 (;) 分隔的電子郵件地址字串,用來新增至訊息的 [收件者] 欄位。A semicolon (;) delimited string of email addresses to add to the message's To field.
ccRecipientsccRecipients 以分號 (;) 分隔的電子郵件地址字串,用來新增至訊息的 [Cc](副本)欄位。A semicolon (;) delimited string of email addresses to add to the message's Cc (carbon copy) field.
bccRecipientsbccRecipients 以分號 (;) 分隔的電子郵件地址字串,用來新增至訊息的 [Bcc](密件副本)欄位。A semicolon (;) delimited string of email addresses to add to the message's Bcc (blind carbon copy) field.

此程式碼片段顯示自訂電子郵件訊息的 channelData 屬性範例。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"
}

建立不失真的 Slack 訊息Create a full-fidelity Slack message

若要建立不失真的 Slack 訊息,請將 Activity 物件的 channelData 屬性設定為 JSON 物件,以指定 Slack 訊息Slack 附件和/或 Slack 按鈕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.

注意

若要在 Slack 訊息中支援按鈕,您必須在將 Bot 連線至 Slack 通道時啟用 [互動式訊息] 。To support buttons in Slack messages, you must enable Interactive Messages when you connect your bot to the Slack channel.

此程式碼片段顯示自訂 Slack 訊息的 channelData 屬性範例。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"
                }
            ]
        }
    ]
}

當使用者按一下 Slack 訊息中的按鈕時,Bot 會收到回應訊息,其中的 channelData 屬性已填入 payload JSON 物件。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. payload 物件會指定原始訊息的內容、識別已按下的按鈕,並識別按下按鈕的使用者。The payload object specifies contents of the original message, identifies the button that was clicked, and identifies the user who clicked the button.

此程式碼片段顯示當使用者按一下 Slack 訊息中的按鈕時,Bot 所收到的訊息中所含有的 channelData 屬性範例。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/..."
    }
}

Bot 可以透過正常方式回覆此訊息,也可以將其回應直接張貼到 payload 物件之 response_url 屬性所指定的端點。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. 如需何時及如何將回應張貼到 response_url 的資訊,請參閱 Slack 按鈕For information about when and how to post a response to the response_url, see Slack Buttons.

建立 Facebook 通知Create a Facebook notification

若要建立 Facebook 通知,請將 Activity 物件的 channelData 屬性設定為指定這些屬性的 JSON 物件:To create a Facebook notification, set the Activity object's channelData property to a JSON object that specifies these properties:

屬性Property 描述Description
notification_typenotification_type 通知類型 (例如 REGULARSILENT_PUSHNO_PUSH)。The type of notification (e.g., REGULAR, SILENT_PUSH, NO_PUSH).
attachmentattachment 指定影像、視訊或其他多媒體類型的附件,或是回條等樣板化附件。An attachment that specifies an image, video, or other multimedia type, or a templated attachment such as a receipt.

注意

如需 notification_type 屬性和 attachment 屬性的格式和內容詳細資料,請參閱 Facebook API 文件For details about format and contents of the notification_type property and attachment property, see the Facebook API documentation.

此程式碼片段顯示 Facebook 回條附件的 channelData 屬性範例。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",
            . . .
        }
    }
}

建立 Telegram 訊息Create a Telegram message

若要建立訊息來實作 Telegram 特定動作 (例如,共用語音備忘或貼紙),請將 Activity 物件的 channelData 屬性設定為會指定這些屬性的 JSON 物件: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
methodmethod 要呼叫的 Telegram Bot API 方法。The Telegram Bot API method to call.
參數parameters 所指定方法的參數。The parameters of the specified method.

支援下列 Telegram 方法:These Telegram methods are supported:

  • answerInlineQueryanswerInlineQuery
  • editMessageCaptioneditMessageCaption
  • editMessageReplyMarkupeditMessageReplyMarkup
  • editMessageTexteditMessageText
  • forwardMessageforwardMessage
  • kickChatMemberkickChatMember
  • sendAudiosendAudio
  • sendChatActionsendChatAction
  • sendContactsendContact
  • sendDocumentsendDocument
  • sendLocationsendLocation
  • sendMessagesendMessage
  • sendPhotosendPhoto
  • sendStickersendSticker
  • sendVenuesendVenue
  • sendVideosendVideo
  • sendVoicesendVoice
  • unbanChateMemberunbanChateMember

如需這些 Telegram 方法和其參數的詳細資訊,請參閱 Telegram Bot API 文件For details about these Telegram methods and their parameters, see the Telegram Bot API documentation.

注意

  • chat_id 參數通用於所有 Telegram 方法。The chat_id parameter is common to all Telegram methods. 如果您未指定 chat_id 作為參數,架構會為您提供識別碼。If you do not specify chat_id as a parameter, the framework will provide the ID for you.
  • 不要傳遞內嵌檔案內容,而是應該指定使用 URL 和媒體類型的檔案,如下列範例所示。Instead of passing file contents inline, specify the file using a URL and media type as shown in the example below.
  • 在 Bot 從 Telegram 通道所收到的每則訊息內,channelData 屬性會包含 Bot 先前傳送的訊息。Within each message that your bot receives from the Telegram channel, the channelData property will include the message that your bot sent previously.

此程式碼片段顯示 channelData 屬性範例,此屬性指定單一 Telegram 方法。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",
        }
    }
}

此程式碼片段顯示 channelData 屬性範例,此屬性指定 Telegram 方法陣列。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"
        }
    }
]

建立原生的 Kik 訊息Create a native Kik message

若要建立原生的 Kik 訊息,請將 Activity 物件的 channelData 屬性設定為指定此屬性的 JSON 物件:To create a native Kik message, set the Activity object's channelData property to a JSON object that specifies this property:

屬性Property 描述Description
messagesmessages Kik 訊息的陣列。An array of Kik messages. 如需 Kik 訊息格式的詳細資訊,請參閱 Kik 訊息格式For details about Kik message format, see Kik Message Formats.

此程式碼片段顯示原生 Kik 訊息的 channelData 屬性範例。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"
                }
        }
    ]
}

其他資源Additional resources