傳送主動式通知給使用者

發行項
05/02/2024

適用於： 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 如何取得交談參考的互動圖表，並用它來傳送主動式訊息。

擷取和儲存交談參考

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

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);
}

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;
}

ProactiveBot.java

@Override
protected CompletableFuture<Void> onConversationUpdateActivity(TurnContext turnContext) {
    addConversationReference(turnContext.getActivity());
    return super.onConversationUpdateActivity(turnContext);
}

// adds a ConversationReference to the shared Map.
private void addConversationReference(Activity activity) {
    ConversationReference conversationReference = activity.getConversationReference();
    conversationReferences.put(conversationReference.getUser().getId(), conversationReference);
}

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 會對應至區域化伺服器。

注意

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

傳送主動式訊息

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

擷取要傳送主動式訊息之交談的參考。
呼叫配接器的 繼續交談 方法，並提供交談參考和回合處理程式委派來使用。（繼續交談方法會產生參考交談的回合內容，然後呼叫指定的回合處理程式委派。
在委派中，使用回合內容來傳送主動式訊息。在此，委派是在通知控制器上定義，並將主動式訊息傳送給使用者。

注意

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

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

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");
    }
}

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();
});

NotifyController.java

每次要求 Bot 的通知頁面時，通知控制器會從字典擷取交談參考。然後控制器會使用 continueConversation 方法來傳送主動式訊息。

@RestController
public class NotifyController {
    /**
     * The BotFrameworkHttpAdapter to use. Note is is provided by dependency
     * injection via the constructor.
     *
     * @see com.microsoft.bot.integration.spring.BotDependencyConfiguration
     */
    private final BotFrameworkHttpAdapter adapter;

    private ConversationReferences conversationReferences;
    private String appId;

    @Autowired
    public NotifyController(
        BotFrameworkHttpAdapter withAdapter,
        Configuration withConfiguration,
        ConversationReferences withReferences
    ) {
        adapter = withAdapter;
        conversationReferences = withReferences;
        appId = withConfiguration.getProperty("MicrosoftAppId");
    }

    @GetMapping("/api/notify")
    public ResponseEntity<Object> proactiveMessage() {
        for (ConversationReference reference : conversationReferences.values()) {
            adapter.continueConversation(
                appId, reference, turnContext -> turnContext.sendActivity("proactive hello").thenApply(resourceResponse -> null)
            );
        }

        // Let the caller know proactive messages have been sent
        return new ResponseEntity<>(
            "<html><body><h1>Proactive messages have been sent.</h1></body></html>",
            HttpStatus.ACCEPTED
        );
    }
}

每次要求 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，您可以使用空字串（“” ）。

測試您的機器人

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

其他資訊

需求

您必須先參考對話，Bot 才能傳送主動式訊息。您的 Bot 可以從使用者收到的任何活動擷取交談參考，但這通常需要使用者至少與 Bot 互動一次，Bot 才能傳送主動式訊息。

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

設計考量

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

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

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

關於主動式回合

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

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

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

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

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

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

下一步

實作循序對話流程

共用方式為