使用 Bot 連接器 API 傳送和接收訊息

發行項
10/09/2024

Bot Connector 服務可讓 Bot 跨多個通道 (例如電子郵件、Slack 等) 進行通訊。它可藉由轉接從 Bot 至通道和從通道至 Bot 的活動，來協助 Bot 和使用者之間的通訊。每個活動都包含資訊，可用於將訊息以及訊息建立者、訊息的內容和訊息收件者的相關資訊，路由傳送至適當的目的地。本文說明如何使用 Bot Connector 服務來交換通道上的 Bot 和使用者之間的訊息活動。

回覆訊息

建立回覆

當使用者將傳送訊息至聊天機器人時，聊天機器人會以 message 類型的活動物件收到訊息。若要建立使用者訊息的回覆，請建立新的 Activity 物件，並從設定下列屬性開始：

屬性	值
交談	將此屬性設為使用者訊息中 `conversation` 屬性的內容。
從	將此屬性設為使用者訊息中 `recipient` 屬性的內容。
地區設定	將此屬性設為使用者訊息中 `locale` 屬性的內容 (若指定)。
收件者	將此屬性設為使用者訊息中 `from` 屬性的內容。
replyToId	將此屬性設為使用者訊息中 `id` 屬性的內容。
type	請將此屬性設定為 message。

接下來，設定屬性 (該屬性會指定您想要傳達給使用者的資訊)。例如，您可以設定 text 屬性來指定要顯示在訊息中的文字、設定 speak 屬性來指定您 Bot 要說出的文字，並設定 attachments 屬性來指定要包含在訊息中的媒體附件或複合式資訊卡 (Rich Card)。如需常用訊息屬性的詳細資訊，請參閱建立訊息。

傳送回覆

在連入活動中使用 serviceUrl 屬性以識別基底 URI (您的 Bot 應該使用該 URI 來發出其回應)。

若要傳送回覆，請發出此要求：

POST /v3/conversations/{conversationId}/activities/{activityId}

在此要求 URI 中，將 {conversationId} 取代為您 (回覆) 活動內 conversation 物件的 id 屬性值，並將 {activityId} 取代為您 (回覆) 活動內 replyToId 屬性的值。將要求的本文設定為您所建立要代表回覆的活動物件。

下列範例會示範將簡單純文字回覆傳送給使用者郵件的要求。在此範例要求中，https://smba.trafficmanager.net/teams 表示基底 URI，您的 Bot 所發出之要求的基底 URI 可能和這個不同。如需設定基底 URI 的詳細資料，請參閱 API 參考。

POST https://smba.trafficmanager.net/teams/v3/conversations/abcd1234/activities/5d5cdc723 
Authorization: Bearer ACCESS_TOKEN 
Content-Type: application/json

{
    "type": "message",
    "from": {
        "id": "12345678",
        "name": "Pepper's News Feed"
    },
    "conversation": {
        "id": "abcd1234",
        "name": "Convo1"
   },
   "recipient": {
        "id": "1234abcd",
        "name": "SteveW"
    },
    "text": "My bot's reply",
    "replyToId": "5d5cdc723"
}

傳送 (非回覆) 訊息

您 Bot 所傳送的大部分訊息，會在它從使用者接收到的回覆訊息中。不過，您的 Bot 有時可能需要將訊息傳送至交談，而該交談不是使用者的任何訊息直接回復。例如，您的 Bot 可能需要啟動新的對話主題，或在對話結尾傳送再見訊息。

若要將訊息傳送至不是直接回復使用者任何訊息的交談，請發出此要求：

POST /v3/conversations/{conversationId}/activities

在此要求 URI 中，將 {conversationId} 取代為對話的識別碼。

將要求的本文設定為您所建立要代表回覆的活動物件。

注意

Bot Framework 不會對 Bot 可能傳送的訊息數目施加任何限制。不過，大部分的通道會強制執行節流限制，限制 Bot 在短時間內傳送大量的訊息。此外，如果 Bot 連續快速地傳送多則訊息，通道可能不一定會依照正確順序轉譯訊息。

開始對話

您的 Bot 有時候可能需要起始與一或多位使用者的對話。若要在通道上開始與使用者對話，您的 Bot 必須知道其帳戶資訊，以及該通道上的使用者帳戶資訊。

提示

如果您的 Bot 在未來可能需要開始與其使用者對話，請快取使用者帳戶資訊、其他相關資訊 (例如使用者喜好設定和地區設定) 和服務 URL (用以作為「開始對話」要求中的基底 URI)。

若要開始對話，請發出此要求：

POST /v3/conversations

將要求的本文設定為ConversationParameters物件，該物件會指定聊天機器人的帳戶資訊，和您想要包含在對話中的使用者帳戶資訊。

注意

並非所有通道都支援群組對話。請參閱通道的文件，判斷通道是否支援群組對話，並識別通道允許對話中的參與者數目上限。

下列範例顯示開始的對話要求。在此範例要求中，https://smba.trafficmanager.net/teams 表示基底 URI，您的 Bot 所發出之要求的基底 URI 可能和這個不同。如需設定基底 URI 的詳細資料，請參閱 API 參考。

POST https://smba.trafficmanager.net/teams/v3/conversations 
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

{
    "bot": {
        "id": "12345678",
        "name": "bot's name"
    },
    "isGroup": false,
    "members": [
        {
            "id": "1234abcd",
            "name": "recipient's name"
        }
    ],
    "topicName": "News Alert"
}

如果對話是以指定的使用者所建立，回應就會包含識別對話的識別碼。

{
    "id": "abcd1234"
}

然後，您的 Bot 可以使用這個對話識別碼，將訊息傳送給對話中的使用者。

共用方式為