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

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 可以使用這個對話識別碼，將訊息傳送給對話中的使用者。

其他資源

• 建立訊息
• Bot Framework -- 活動結構描述