Wysyłanie proaktywnych powiadomień do użytkowników

DOTYCZY: ZESTAW SDK w wersji 4

Zazwyczaj bot wysyła wiadomość do użytkownika bezpośrednio w odpowiedzi na odbieranie komunikatu od użytkownika. Od czasu do czasu bot może wymagać wysłania proaktywnego komunikatu w odpowiedzi na bodźce, które nie pochodzą od użytkownika.

Proaktywne komunikaty mogą być przydatne w różnych scenariuszach. Jeśli na przykład użytkownik poprosił wcześniej bota o monitorowanie ceny produktu, bot może powiadomić użytkownika, jeśli cena produktu spadła o 20%. Lub jeśli bot wymaga trochę czasu na skompilowanie odpowiedzi na pytanie użytkownika, może poinformować użytkownika o opóźnieniu i zezwolić na kontynuowanie konwersacji w międzyczasie. Po zakończeniu kompilowania odpowiedzi na pytanie bot udostępni te informacje użytkownikowi.

W tym artykule omówiono ogólnie informacje o proaktywnych komunikatach dotyczących botów. Aby uzyskać informacje o proaktywnych komunikatach w usłudze Microsoft Teams, zobacz

• Przykład bota konwersacji usługi Teams w języku C#, JavaScript, Java lub Python.
• Dokumentacja usługi Microsoft Teams dotycząca sposobu wysyłania proaktywnych komunikatów.

Uwaga

Zestawy SDK języka JavaScript, C# i Python platformy Bot Framework będą nadal obsługiwane, jednak zestaw SDK języka Java jest wycofywany z ostatecznym długoterminowym wsparciem kończącym się w listopadzie 2023 r.

Istniejące boty utworzone za pomocą zestawu JAVA SDK będą nadal działać.

W przypadku tworzenia nowych botów rozważ użycie programu Microsoft Copilot Studio i przeczytaj o wyborze odpowiedniego rozwiązania copilot.

Aby uzyskać więcej informacji, zobacz Przyszłość tworzenia botów.

Wymagania wstępne

• Poznaj podstawy bota.
• Kopia przykładowych komunikatów proaktywnych w języku C#, JavaScript, Java lub Python. Przykład służy do wyjaśnienia proaktywnych komunikatów w tym artykule.

Informacje o proaktywnym przykładzie

Ogólnie rzecz biorąc, bot jako aplikacja ma kilka warstw:

• Aplikacja internetowa, która może akceptować żądania HTTP, a w szczególności obsługuje punkt końcowy obsługi komunikatów.
• Adapter obsługujący łączność z kanałami.
• Procedura obsługi kolei, zazwyczaj hermetyzowana w klasie bota , która obsługuje rozumowanie konwersacyjne dla aplikacji bota.

W odpowiedzi na przychodzący komunikat od użytkownika aplikacja wywołuje metodę działania procesu karty, która tworzy kontekst turn and turn, wywołuje potok oprogramowania pośredniczącego, a następnie wywołuje procedurę obsługi kolei bota.

Aby zainicjować proaktywny komunikat, aplikacja bota musi mieć możliwość odbierania innych danych wejściowych. Logika aplikacji do inicjowania proaktywnego komunikatu wykracza poza zakres zestawu SDK. W tym przykładzie punkt końcowy powiadamiania oprócz standardowego punktu końcowego komunikatów jest używany do wyzwalania proaktywnego zwrotu.

W odpowiedzi na żądanie GET w tym punkcie końcowym powiadamiania aplikacja wywołuje metodę kontynuowania konwersacji karty, która zachowuje się podobnie do metody działania procesu. Kontynuuj metodę konwersacji :

• Przyjmuje odpowiednie odwołanie do konwersacji dla użytkownika i metody wywołania zwrotnego do użycia w celu proaktywnego obrotu.
• Tworzy działanie zdarzenia i kontekst turn dla proaktywnego zwrotu.
• Wywołuje potok oprogramowania pośredniczącego karty.
• Wywołuje podaną metodę wywołania zwrotnego.
• Kontekst kolei używa odwołania do konwersacji do wysyłania dowolnych wiadomości do użytkownika.

Przykład zawiera bota, punkt końcowy komunikatów i dodatkowy punkt końcowy używany do wysyłania proaktywnych komunikatów do użytkownika, jak pokazano na poniższej ilustracji.

Pobieranie i przechowywanie odwołania do konwersacji

Gdy bot Framework Emulator łączy się z botem, bot otrzymuje dwa działania aktualizacji konwersacji. W procedurze obsługi działań aktualizacji konwersacji bota odwołanie do konwersacji jest pobierane i przechowywane w słowniku, jak pokazano poniżej.

C#

Boty\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

boty/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

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

Python

boty/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

Odwołanie do konwersacji zawiera właściwość konwersacji , która opisuje konwersację, w której istnieje działanie. Konwersacja zawiera właściwość użytkownika, która zawiera listę użytkowników uczestniczących w konwersacji oraz właściwość adresu URL usługi wskazującą, gdzie mogą być wysyłane odpowiedzi na bieżące działanie. Do wysyłania proaktywnych wiadomości do użytkowników potrzebna jest prawidłowa dokumentacja konwersacji. (W przypadku kanału usługi Teams adres URL usługi jest mapowany na serwer regionalizowany).

Uwaga

W rzeczywistym scenariuszu można utrwalać odwołania do konwersacji w bazie danych zamiast używać obiektu w pamięci.

Wyślij proaktywną wiadomość

Drugi kontroler, kontroler powiadamiania, jest odpowiedzialny za wysyłanie proaktywnego komunikatu do użytkownika. W celu wygenerowania proaktywnego komunikatu użyto poniższych kroków.

1. Pobiera odwołanie do konwersacji, do której ma być wysyłana aktywna wiadomość.
2. Wywołuje metodę kontynuowania konwersacji adaptera , podając odwołanie do konwersacji i delegata programu obsługi kolei do użycia. (Metoda kontynuuj konwersacji generuje kontekst turn dla konwersacji, do których się odwołuje, a następnie wywołuje określonego delegata programu obsługi kolei).
3. W delegatu używa kontekstu kolei do wysyłania proaktywnego komunikatu. W tym miejscu delegat jest zdefiniowany na kontrolerze powiadamiania i wysyła proaktywny komunikat do użytkownika.

Uwaga

Chociaż każdy kanał powinien używać stabilnego adresu URL usługi, adres URL może ulec zmianie w czasie. Aby uzyskać więcej informacji na temat adresu URL usługi, zobacz sekcje Podstawowa struktura działań i Adres URL usługi schematu działania platformy Bot Framework.

Jeśli adres URL usługi ulegnie zmianie, poprzednie odwołania do konwersacji nie będą już prawidłowe i wywołania do kontynuowania konwersacji wygenerują błąd lub wyjątek. W takim przypadku bot będzie musiał uzyskać nowe odwołanie do konwersacji dla użytkownika, zanim będzie mógł ponownie wysyłać proaktywne wiadomości.

C#

Controllers\NotifyController .cs

Za każdym razem, gdy jest żądana strona powiadamiania bota, kontroler powiadamiania pobiera odwołania do konwersacji ze słownika. Następnie kontroler używa ContinueConversationAsync metod i BotCallback do wysyłania proaktywnego komunikatu.

[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

Za każdym razem, gdy żądana jest strona serwera /api/notify , serwer pobiera odwołania do konwersacji ze słownika. Następnie serwer używa continueConversation metody do wysyłania proaktywnego komunikatu. Parametr to continueConversation funkcja, która służy jako procedura obsługi kolei bota dla tego turnu.

    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

Za każdym razem, gdy jest żądana strona powiadamiania bota, kontroler powiadamiania pobiera odwołania do konwersacji ze słownika. Następnie kontroler używa continueConversation metody do wysyłania proaktywnego komunikatu.

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

Python

Za każdym razem, gdy jest żądana strona powiadamiania bota, serwer pobiera odwołania do konwersacji ze słownika. Następnie serwer używa metody do _send_proactive_message wysyłania proaktywnego komunikatu.

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

Aby wysłać proaktywny komunikat, karta wymaga identyfikatora aplikacji bota. W środowisku produkcyjnym można użyć identyfikatora aplikacji bota. Aby przetestować bota lokalnie za pomocą emulatora, możesz użyć pustego ciągu ("").

Testowanie bota

1. Jeśli jeszcze tego nie zrobiono, zainstaluj program Bot Framework Emulator.
2. Uruchom przykład lokalnie na maszynie.
3. Uruchom emulator i połącz się z botem.
4. Załaduj do strony interfejsu API/powiadamiania bota. Spowoduje to wygenerowanie proaktywnego komunikatu w emulatorze.

Dodatkowe informacje

Wymagania

Aby można było wysłać proaktywną wiadomość, bot potrzebuje odwołania do konwersacji. Bot może pobrać odwołanie do konwersacji z dowolnego działania otrzymanego od użytkownika, ale zazwyczaj wymaga to od użytkownika interakcji z botem co najmniej raz, zanim bot będzie mógł wysłać proaktywną wiadomość.

Wiele kanałów uniemożliwia botowi wysyłanie wiadomości użytkownikowi, chyba że użytkownik wysyła wiadomość do bota co najmniej raz. Niektóre kanały zezwalają na wyjątki. Na przykład kanał usługi Teams umożliwia botowi wysyłanie proaktywnej (lub 1-na-1) wiadomości do osób w już ustalonej konwersacji grupowej, która zawiera bota.

Uwagi dotyczące projektowania

Podczas implementowania proaktywnych komunikatów w botze nie wysyłaj kilku proaktywnych komunikatów w krótkim czasie. Niektóre kanały wymuszają ograniczenia dotyczące tego, jak często bot może wysyłać komunikaty do użytkownika i wyłączy bota, jeśli narusza te ograniczenia.

W przypadku najprostszego typu proaktywnego komunikatu bot przeplata wiadomość z konwersacją po wyzwoleniu, bez względu na bieżący stan lub temat konwersacji. W tym scenariuszu proaktywny komunikat przerywa normalny przepływ konwersacji.

Aby wydajniej obsługiwać powiadomienia, rozważ inne sposoby integrowania powiadomienia z przepływem konwersacji, takie jak ustawienie flagi w stanie konwersacji lub dodanie powiadomienia do kolejki.

Informacje o proaktywnym kolei

Metoda kontynuacji konwersacji używa odwołania do konwersacji i procedury obsługi wywołania zwrotnego w celu:

1. Utwórz kolei, w którym aplikacja bota może wysyłać proaktywny komunikat. Karta tworzy event działanie dla tego kolei, z jego nazwą ustawioną na "ContinueConversation".
2. Wyślij przekręć potok oprogramowania pośredniczącego karty.
3. Wywołaj procedurę obsługi wywołania zwrotnego w celu wykonania logiki niestandardowej.

W przykładzie proaktywnych komunikatów program obsługi wywołania zwrotnego jest zdefiniowany w kontrolerze powiadamiania i wysyła wiadomość bezpośrednio do konwersacji bez wysyłania proaktywnego działania za pośrednictwem normalnego programu obsługi kolei bota. Przykładowy kod również nie uzyskuje dostępu do stanu bota ani nie aktualizuje go w trybie proaktywnym.

Wiele botów jest stanowych i używa ich do zarządzania konwersacją na wiele kolei. Gdy metoda kontynuacji konwersacji tworzy kontekst turn, kolei będzie mieć skojarzony prawidłowy stan użytkownika i konwersacji i można zintegrować proaktywne przekształcenia w logikę bota. Jeśli potrzebujesz logiki bota, aby wiedzieć o proaktywnym komunikacie, masz kilka opcji, aby to zrobić. Masz następujące możliwości:

• Podaj program obsługi kolei bota jako procedurę obsługi wywołania zwrotnego. Bot otrzyma następnie działanie zdarzenia "ContinueConversation".
• Użyj procedury obsługi wywołania zwrotnego turn, aby najpierw dodać informacje do kontekstu turn, a następnie wywołać procedurę obsługi kolei bota.

W obu tych przypadkach należy zaprojektować logikę bota w celu obsługi proaktywnego zdarzenia.

Następne kroki

Implementowanie sekwencyjnego przepływu konwersacji