傳送主動式通知給使用者

適用於： SDK v4

一般而言，Bot 會直接將訊息傳送給使用者，以回應使用者接收訊息。 有時候，Bot 可能需要傳送一則主動式訊息，這種訊息是回應非使用者來源的刺激。

主動式訊息在各種案例中很有用。 例如，如果使用者先前已要求 Bot 監視產品的價格，Bot 可以在產品價格已下降 20% 時警示使用者。 或者，如果 Bot 需要一些時間來編譯使用者問題的回應，它可能會通知用戶延遲，並允許對話同時繼續。 當 Bot 完成對問題的響應編譯時，它會與使用者共用該資訊。

本文涵蓋一般 Bot 的主動式訊息相關信息。 如需 Microsoft Teams 中主動式訊息的相關信息，請參閱

• C#、JavaScript、Java 或 Python 中的 Teams 交談 Bot 範例。
• Microsoft Teams 文件，說明如何 傳送主動式訊息。

注意

Bot Framework JavaScript、C# 和 Python SDK 將會繼續受到支援，不過，Java SDK 即將淘汰，最終長期支援將於 2023 年 11 月結束。

使用 Java SDK 建置的現有 Bot 將繼續運作。

針對新的 Bot 建置，請考慮使用 Microsoft Copilot Studio ，並閱讀 選擇正確的 Copilot 解決方案。

如需詳細資訊，請參閱 Bot 建置的未來。

必要條件

• 瞭解 Bot 基本概念。
• C#、JavaScript、Java 或 Python 中的主動式訊息範例複本。 此範例用來說明本文中的主動式傳訊。

關於主動式範例

一般而言，Bot 作為應用程式有一些層級：

• 可接受 HTTP 要求的 Web 應用程式，並特別支援傳訊端點。
• 處理通道連線的配接器。
• 回合的處理程式，通常封裝在 Bot 類別中，以處理 Bot 應用程式的交談推理。

為了回應使用者傳入的訊息，應用程式會呼叫配接器的 處理活動 方法，該方法會建立一個回合和其回合上下文、調用中介軟體管線，然後呼叫 Bot 的回合處理程序。

若要起始主動式訊息，Bot 應用程式必須能夠接收其他輸入。 起始主動式訊息的應用程式邏輯不在 SDK 的範圍內。 在此範例中，除了標準訊息端點之外，也會使用通知端點來觸發主動回合。

為了回應此通知端點上的 GET 要求，應用程式會呼叫配接器的 繼續交談 方法，其行為類似於 進程活動 方法。 繼續 對話 方法：

• 針對使用者和回呼方法採用適當的交談參考，以用於主動回合。
• 建立主動回合的事件活動和回合內容。
• 呼叫配接器的中間件管線。
• 呼叫所提供的回調方法。
• 回合上下文使用對話參考來將任何訊息傳送給使用者。

此範例具有 Bot、訊息端點，以及用來將主動式訊息傳送給使用者的額外端點，如下圖所示。

擷取和儲存交談參考

當 Bot Framework 模擬器連線到 Bot 時，Bot 會收到兩個對話更新活動。 在 Bot 的交談更新活動處理程式中，交談參考會擷取並儲存在字典中，如下所示。

C#

Bots\ProactiveBot.cs

private void AddConversationReference(Activity activity)
{
    var conversationReference = activity.GetConversationReference();
    _conversationReferences.AddOrUpdate(conversationReference.User.Id, conversationReference, (key, newValue) => conversationReference);
}

protected override Task OnConversationUpdateActivityAsync(ITurnContext<IConversationUpdateActivity> turnContext, CancellationToken cancellationToken)
{
    AddConversationReference(turnContext.Activity as Activity);

    return base.OnConversationUpdateActivityAsync(turnContext, cancellationToken);
}

JavaScript

bots/proactiveBot.js

this.onConversationUpdate(async (context, next) => {
    this.addConversationReference(context.activity);

    await next();
});

addConversationReference(activity) {
    const conversationReference = TurnContext.getConversationReference(activity);
    this.conversationReferences[conversationReference.conversation.id] = conversationReference;
}

Java

ProactiveBot.java

警告

您要尋找的範例看起來已經移動！ 放心，我們正在努力解決這個問題。

Python

bots/proactive_bot.py

async def on_conversation_update_activity(self, turn_context: TurnContext):
    self._add_conversation_reference(turn_context.activity)
    return await super().on_conversation_update_activity(turn_context)

def _add_conversation_reference(self, activity: Activity):
    """
    This populates the shared Dictionary that holds conversation references. In this sample,
    this dictionary is used to send a message to members when /api/notify is hit.
    :param activity:
    :return:
    """
    conversation_reference = TurnContext.get_conversation_reference(activity)
    self.conversation_references[
        conversation_reference.user.id
    ] = conversation_reference

交談參考包含一個交談屬性，該屬性用來描述活動所在的會話。 交談包含一個 用戶 屬性，其中列出參與交談的使用者，以及 指出傳送目前活動回復位置的服務 URL 屬性。 需要有效的交談參考，才能將主動式訊息傳送給使用者。 （針對 Teams 頻道，服務 URL 會對應至區域化伺服器。

注意

在真實世界的案例中，您會在資料庫中保存交談參考，而不是在記憶體中使用物件。

傳送主動式訊息

第二個 控制器，通知 控制器，負責將主動式訊息傳送給使用者。 它會使用下列步驟來產生主動式訊息。

1. 取得要傳送主動式訊息的交談參照。
2. 呼叫配接器的 繼續交談 方法，並提供交談參考和處理委派函式以便使用。 （繼續交談方法會產生所參考的交談的回合上下文，然後呼叫指定的回合處理委派。）
3. 在代理中，使用回合上下文來傳送主動訊息。 在此，委派是在通知控制器上定義，並將主動式訊息傳送給使用者。

注意

雖然每個通道都應該使用穩定的服務 URL，但 URL 可能會隨著時間而變更。 如需服務 URL 的詳細資訊，請參閱 Bot Framework 活動架構的基本活動結構和服務 URL 區段。

如果服務 URL 變更，先前的交談參考將不再有效，而繼續交談的呼叫將會產生錯誤或例外狀況。 在此情況下，您的 Bot 必須取得使用者的新交談參考，才能再次傳送主動式訊息。

C#

Controllers\NotifyController .cs

每當要求 Bot 顯示通知頁面時，通知控制器會從字典中擷取對話參考資料。 然後控制器會使用 ContinueConversationAsync 和 BotCallback 方法來傳送主動式訊息。

[Route("api/notify")]
[ApiController]
public class NotifyController : ControllerBase
{
    private readonly IBotFrameworkHttpAdapter _adapter;
    private readonly string _appId;
    private readonly ConcurrentDictionary<string, ConversationReference> _conversationReferences;

    public NotifyController(IBotFrameworkHttpAdapter adapter, IConfiguration configuration, ConcurrentDictionary<string, ConversationReference> conversationReferences)
    {
        _adapter = adapter;
        _conversationReferences = conversationReferences;
        _appId = configuration["MicrosoftAppId"] ?? string.Empty;
    }

    public async Task<IActionResult> Get()
    {
        foreach (var conversationReference in _conversationReferences.Values)
        {
            await ((BotAdapter)_adapter).ContinueConversationAsync(_appId, conversationReference, BotCallback, default(CancellationToken));
        }
        
        // Let the caller know proactive messages have been sent
        return new ContentResult()
        {
            Content = "<html><body><h1>Proactive messages have been sent.</h1></body></html>",
            ContentType = "text/html",
            StatusCode = (int)HttpStatusCode.OK,
        };
    }

    private async Task BotCallback(ITurnContext turnContext, CancellationToken cancellationToken)
    {
        await turnContext.SendActivityAsync("proactive hello");
    }
}

JavaScript

index.js

每次要求伺服器的 /api/notify 頁面時，伺服器會從詞典中擷取對話參考。 伺服器接著會使用 continueConversation 方法來傳送主動式訊息。 continueConversation的參數是函式，做為這個回合的 Bot 回合處理程式。

    res.setHeader('Content-Type', 'text/html');
    res.writeHead(200);
    res.write('<html><body><h1>Proactive messages have been sent.</h1></body></html>');
    res.end();
});

Java

NotifyController.java

每次請求機器人的通知頁面時，通知控制器會從對應表中擷取對話參考。 然後控制器會使用 continueConversation 方法來傳送主動式訊息。

警告

您要尋找的範例看起來已經移動！ 放心，我們正在努力解決這個問題。

Python

每次請求 Bot 的通知頁面時，伺服器都會從資料庫中擷取會話引用。 伺服器接著會使用 _send_proactive_message 傳送主動式訊息。

if __name__ == "__main__":
    try:
        web.run_app(APP, host="localhost", port=CONFIG.PORT)
    except Exception as error:
        raise error

若要傳送主動式訊息，配接器需要 Bot 的應用程式識別碼。 在生產環境中，您可以使用 Bot 的應用程式識別碼。 若要使用模擬器在本機測試 Bot，您可以使用空字串 （“” ）。

測試您的機器人

1. 如果您尚未這麼做，請安裝 Bot Framework 模擬器。
2. 在本機電腦上執行範例。
3. 啟動模擬器並連線到 Bot。
4. 載入至 Bot 的 API/通知頁面。 這會在模擬器中產生主動式訊息。

其他資訊

需求

在您能傳送主動式訊息之前，您的 Bot 需要一個 對話參考。 您的機器人可以從使用者收到的任何活動中擷取交談參考，但這通常需要使用者至少與機器人互動過一次後，機器人才可以傳送主動訊息。

許多頻道禁止 Bot 傳訊給使用者，除非使用者先傳訊給 Bot 至少一次。 某些通道允許例外狀況。 例如，Teams 頻道可讓您的 Bot 將主動式（或 1 對 1） 訊息傳送給包含 Bot 的已建立群組交談中的個人。

設計考量

在 Bot 中實作主動式訊息時，不要在短時間內傳送數個主動式訊息。 某些通道會強制限制 Bot 傳送訊息給用戶的頻率，並在 Bot 違反這些限制時停用 Bot。

對於最簡單的主動式訊息類型，Bot 會在觸發訊息時將訊息插入交談中，而不考慮交談的目前狀態或主題。 在此案例中，主動式訊息會中斷交談的正常流程。

若要更順暢地處理通知，請考慮將通知整合到交談流程的其他方式，例如在交談狀態中設定旗標，或將通知新增至佇列。

關於積極主動的轉變

繼續交談的方法會使用交談參考和回合回呼處理程式來：

1. 建立 Bot 應用程式可以傳送主動式訊息的回合。 配接器會 event 為此回合建立活動，並將名稱設定為「ContinueConversation」。
2. 透過配接器的中間件管線傳送回合。
3. 呼叫回合回呼處理程式來執行自定義邏輯。

在 主動式訊息 範例中，回合回呼處理程式是在通知控制器中定義，並將訊息直接傳送至交談，而不需要透過 Bot 的一般回合處理程式傳送主動活動。 範例程式代碼也不會存取或更新主動回合上的 Bot 狀態。

許多 Bot 都是具狀態的，並使用狀態來管理多個回合的交談。 當繼續交談方法建立對話回合內容時，該回合將具備正確的使用者和交談狀態，您可以將主動回合整合到 Bot 的邏輯中。 如果您需要 Bot 邏輯留意主動式訊息，您有幾個選項可以這麼做。 您可以：

• 提供 Bot 的輪次處理程式作為回合回呼處理程式。 Bot 接著會收到 「ContinueConversation」 事件活動。
• 使用回合回呼處理程式先將資訊新增至回合內容，然後呼叫 Bot 的回合處理程式。

在這兩種情況下，您必須設計 Bot 邏輯來處理主動式事件。

下一步

實作循序對話流程