實作通道特定的功能

發行項
03/08/2023

適用于： SDK v4

某些通道提供的功能只能使用郵件內文和附件來實作。若要實作通道特定的功能，您可以將原生中繼資料傳遞至活動物件「通道資料」屬性中的通道。例如，Bot 可以使用通道資料屬性，指示 Telegram 傳送貼圖或指示 Office365 傳送電子郵件。

此文章說明如何使用訊息活動的通道資料屬性，來實作此通道特定的功能：

通路	功能
電子郵件	傳送和接收包含本文、主旨和重要性中繼資料的電子郵件。
Facebook	以原生方式傳送 Facebook 通知。
線條	傳送實作 LINE 特定訊息類型的訊息。
Slack	傳送完整逼真度 Slack 訊息。
Teams	處理 Microsoft Teams 訊息中的 @-mentions。
Telegram	執行 Telegram 特定的動作，例如共用語音備忘或貼紙。

注意

活動物件的通道資料屬性值是一個 JSON 物件。因此，本文中的範例會說明各種案例中 channelData JSON 屬性的預期格式。若要使用 .NET 建立 JSON 物件，請使用 JObject (.NET) 類別。

建立自訂電子郵件訊息

若要建立自訂電子郵件訊息，請將活動 channelData 屬性設定為包含下列屬性的 JSON 物件：

屬性	描述
bccRecipients	以分號 (;) 分隔的電子郵件地址字串，用來新增至訊息的 [Bcc]\(密件副本\)欄位。
ccRecipients	以分號 (;) 分隔的電子郵件地址字串，用來新增至訊息的 [Cc]\(副本\)欄位。
htmlBody	會指定電子郵件訊息本文的 HTML 文件。請參閱通道的文件，以取得受支援 HTML 元素和屬性的資訊。
importance	電子郵件的重要性層級。有效值為高、一般和低。預設值為一般。
toRecipients	以分號 (;) 分隔的電子郵件地址字串，用來新增至訊息的 [收件者] 欄位。

使用者與 Bot 之間的傳出和傳入訊息可能會有活動 channelData ，其中包含在上表中指定其屬性的 JSON 物件。下列程式碼片段顯示從 Bot 到使用者之傳入自訂電子郵件訊息的屬性範例 channelData 。

{
    "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",
    }
}

建立 Facebook 通知

若要建立 Facebook 通知，請將活動物件的通道資料屬性設定為指定這些屬性的 JSON 物件：

屬性	描述
notification_type	通知的類型，例如 REGULAR、 SILENT_PUSH或 NO_PUSH。
attachment	指定影像、視訊或其他多媒體類型的附件，或是回條等樣板化附件。

注意

如需 notification_type 屬性和 attachment 屬性的格式和內容詳細資料，請參閱 Facebook API 文件。

此程式碼片段顯示 Facebook 回條附件的 channelData 屬性範例。

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

建立 LINE 訊息

若要建立實作 LINE 特定訊息類型的訊息， (例如貼紙、範本或 LINE 特定動作類型，例如開啟手機相機) ，請將活動物件的通道資料屬性設定為指定 LINE 訊息類型和動作類型的 JSON 物件。

屬性	描述
type	LINE 動作/訊息類型名稱

支援這些 LINE 訊息類型：

貼圖
影像地圖
範本 (按鈕、確認、橫向捲軸)
Flex

您可以在訊息類型 JSON 物件的動作欄位中，指定這些 LINE 動作：

Postback
訊息
URI
Datetimerpicker
相機
Camera roll
Location

如需這些 LINE 方法和其參數的詳細資訊，請參閱 LINE Bot API 文件。

此程式碼片段示範指定通道訊息類型和 ButtonTemplate 三種動作類型的屬性範例 channelData ：「camera」、「cameraRoll」和「datetimepicker」。

"channelData": {
    "type": "template",
    "altText": "This is a buttons template",
    "template": {
        "type": "buttons",
        "thumbnailImageUrl": "https://example.com/bot/images/image.jpg",
        "imageAspectRatio": "rectangle",
        "imageSize": "cover",
        "imageBackgroundColor": "#FFFFFF",
        "title": "Menu",
        "text": "Please select",
        "defaultAction": {
            "type": "uri",
            "label": "View detail",
            "uri": "http://example.com/page/123"
        },
        "actions": [{
                "type": "cameraRoll",
                "label": "Camera roll"
            },
            {
                "type": "camera",
                "label": "Camera"
            },
            {
                "type": "datetimepicker",
                "label": "Select date",
                "data": "storeId=12345",
                "mode": "datetime",
                "initial": "2017-12-25t00:00",
                "max": "2018-01-24t23:59",
                "min": "2017-12-25t00:00"
            }
        ]
    }
}

建立不失真的 Slack 訊息

若要建立完整精確度的 Slack 訊息，請將活動物件的通道資料屬性設定為指定：

注意

若要在 Slack 訊息中支援按鈕，您必須在將 Bot 連線至 Slack 通道時啟用 [互動式訊息] 。

此程式碼片段顯示自訂 Slack 訊息的 channelData 屬性範例。

"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 會收到回應訊息，其中的通道資料屬性已填入 payload JSON 物件。 payload 物件會指定原始訊息的內容、識別已按下的按鈕，並識別按下按鈕的使用者。

此程式碼片段顯示當使用者按一下 Slack 訊息中的按鈕時，Bot 所收到的訊息中所含有的 channelData 屬性範例。

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

Bot 可以透過正常方式回覆此訊息，也可以將其回應直接張貼到 payload 物件的 response_url 屬性所指定的端點。如需何時及如何將回應張貼到 response_url 的資訊，請參閱 Slack 按鈕。

您可以使用下列 JSON 建立動態按鈕：

{
    "text": "Would you like to play a game ? ",
    "attachments": [
        {
            "text": "Choose a game to play!",
            "fallback": "You are unable to choose a game",
            "callback_id": "wopr_game",
            "color": "#3AA3E3",
            "attachment_type": "default",
            "actions": [
                {
                    "name": "game",
                    "text": "Chess",
                    "type": "button",
                    "value": "chess"
                },
                {
                    "name": "game",
                    "text": "Falken's Maze",
                    "type": "button",
                    "value": "maze"
                },
                {
                    "name": "game",
                    "text": "Thermonuclear War",
                    "style": "danger",
                    "type": "button",
                    "value": "war",
                    "confirm": {
                        "title": "Are you sure?",
                        "text": "Wouldn't you prefer a good game of chess?",
                        "ok_text": "Yes",
                        "dismiss_text": "No"
                    }
                }
            ]
        }
    ]
}

若要建立互動式功能表，請使用下列 JSON：

{
    "text": "Would you like to play a game ? ",
    "response_type": "in_channel",
    "attachments": [
        {
            "text": "Choose a game to play",
            "fallback": "If you could read this message, you'd be choosing something fun to do right now.",
            "color": "#3AA3E3",
            "attachment_type": "default",
            "callback_id": "game_selection",
            "actions": [
                {
                    "name": "games_list",
                    "text": "Pick a game...",
                    "type": "select",
                    "options": [
                        {
                            "text": "Hearts",
                            "value": "menu_id_hearts"
                        },
                        {
                            "text": "Bridge",
                            "value": "menu_id_bridge"
                        },
                        {
                            "text": "Checkers",
                            "value": "menu_id_checkers"
                        },
                        {
                            "text": "Chess",
                            "value": "menu_id_chess"
                        },
                        {
                            "text": "Poker",
                            "value": "menu_id_poker"
                        },
                        {
                            "text": "Falken's Maze",
                            "value": "menu_id_maze"
                        },
                        {
                            "text": "Global Thermonuclear War",
                            "value": "menu_id_war"
                        }
                    ]
                }
            ]
        }
    ]
}

將 Bot 新增至 Teams

新增至小組的 Bot 會成為另一個小組成員，而可在交談中被 @mentioned。事實上，Bot 只會在訊息為 @mentioned 時接收訊息，因此通道上的其他交談不會傳送至 Bot。如需詳細資訊，請參閱與 Microsoft Teams Bot 進行通道和群組聊天交談。

因為群組或通道中的 Bot 只會在訊息中提及 (@botname) 時回應，所以群組通道中的 Bot 所接收的每個訊息都包含自己的名稱，而且您必須確定訊息剖析控制碼。此外，Bot 可以剖析出其他被提及的使用者，並且在其訊息中提及使用者。

檢查是否有 @bot 提及並加以移除

Mention[] m = sourceMessage.GetMentions();
var messageText = sourceMessage.Text;

for (int i = 0;i < m.Length;i++)
{
    if (m[i].Mentioned.Id == sourceMessage.Recipient.Id)
    {
        //Bot is in the @mention list.
        //The below example will strip the bot name out of the message, so you can parse it as if it wasn't included. Note that the Text object will contain the full bot name, if applicable.
        if (m[i].Text != null)
            messageText = messageText.Replace(m[i].Text, "");
    }
}

var text = message.text;
if (message.entities) {
    message.entities
        .filter(entity => ((entity.type === "mention") && (entity.mentioned.id.toLowerCase() === botId)))
        .forEach(entity => {
            text = text.replace(entity.text, "");
        });
    text = text.trim();
}

重要

不建議使用 GUID 新增 Bot，以用於測試用途以外的任何專案。這麼做會嚴重限制 Bot 的功能。生產環境中的 Bot 應會隨著應用程式新增至 Teams。請參閱建立 Bot 和測試及偵錯您的 Microsoft Teams Bot。

建立 Telegram 訊息

若要建立訊息來實作 Telegram 特定動作 (例如，共用語音備忘或貼圖)，請將活動物件的通道資料屬性設定為會指定這些屬性的 JSON 物件：

屬性	描述
method	要呼叫的 Telegram Bot API 方法。
參數	所指定方法的參數。

支援下列 Telegram 方法：

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

如需這些 Telegram 方法和其參數的詳細資訊，請參閱 Telegram Bot API 文件。

注意

chat_id 參數通用於所有 Telegram 方法。如果您未指定 chat_id 為參數，架構會為您提供識別碼。
不要傳遞內嵌檔案內容，而是應該指定使用 URL 和媒體類型的檔案，如下列範例所示。
在 Bot 從 Telegram 通道所收到的每則訊息內，ChannelData 屬性會包含 Bot 先前傳送的訊息。

此程式碼片段顯示指定單一 Telegram 方法的屬性範例 channelData ：

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

此程式碼片段示範指定 Telegram 方法陣列的屬性範例 channelData ：

"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"
        }
    }
]

實作 Telegram 方法時，您的 Bot 會收到回應訊息，其中的頻道資料屬性已填入 JSON 物件。此回應物件會指定原始訊息的內容，包括 update_id 和一個選擇性參數 (最多)。如需有關接收傳入回應的詳細資訊，請參閱取得更新。

此程式碼片段顯示 Bot 在建立輪詢時收到的訊息中的屬性範例 channelData ：

"channelData": {
    "update_id": 43517575,
    "message": {
        "message_id": 618,
        "from": {
            "id": 803613355,
            "is_bot": false,
            "first_name": "Joe",
            "last_name": "Doe",
            "username": "jdoe",
            "language_code": "en"
        },
        "chat": {
            "id": 803613355,
            "first_name": "Joe",
            "last_name": "Doe",
            "username": "jdoe",
            "type": "private"
        },
        "date": 1582577834,
        "poll": {
        "id": "5089525250643722242",
        "question": "How to win?",
        "options": [
            {
                "text": "Be the best",
                "voter_count": 0
            },
            {
                "text": "Help those in need",
                "voter_count": 0
            },
            {
                "text": "All of the above",
                "voter_count": 0
            }
        ],
        "total_voter_count": 0,
        "is_closed": false,
        "is_anonymous": true,
        "type": "regular",
        "allows_multiple_answers": false
        }
    }
}