Odesílání proaktivních oznámení uživatelům

PLATÍ PRO: SDK v4

Robot obvykle pošle uživateli zprávu přímo v reakci na přijetí zprávy od uživatele. Někdy může robot potřebovat odeslat proaktivní zprávu, zprávu v reakci na podněty, které nepocházejí od uživatele.

Proaktivní zprávy můžou být užitečné v různých scénářích. Pokud například uživatel dříve požádal robota o monitorování ceny produktu, může robot upozornit uživatele, pokud cena produktu klesla o 20 %. Nebo pokud robot vyžaduje nějakou dobu ke kompilaci odpovědi na otázku uživatele, může uživatele informovat o zpoždění a umožnit konverzaci pokračovat do té doby. Jakmile robot dokončí kompilaci odpovědi na otázku, bude informace sdílet s uživatelem.

Tento článek se zabývá informacemi o proaktivních zprávách pro roboty obecně. Informace o proaktivních zprávách v Microsoft Teams najdete v tématu

• Ukázka chatovacího robota Teams v C#, JavaScriptu, Javě nebo Pythonu
• Dokumentace k Microsoft Teams o tom, jak odesílat proaktivní zprávy.

Poznámka:

Sady SDK služby Bot Framework JavaScript, C# a Python budou nadále podporovány, ale sada Java SDK se vyřazuje s konečnou dlouhodobou podporou končící v listopadu 2023.

Stávající roboti sestavení pomocí sady Java SDK budou i nadále fungovat.

Při vytváření nových robotů zvažte použití aplikace Microsoft Copilot Studio a přečtěte si o výběru správného řešení copilotu.

Další informace najdete v tématu Budoucnost vytváření robotů.

Požadavky

• Seznamte se se základy robota.
• Kopie proaktivních zpráv v jazyce C#, JavaScript, Java nebo Python. Ukázka se používá k vysvětlení proaktivního zasílání zpráv v tomto článku.

O proaktivní ukázce

Obecně platí, že robot jako aplikace má několik vrstev:

• Webová aplikace, která může přijímat požadavky HTTP a konkrétně podporuje koncový bod zasílání zpráv.
• Adaptér, který zpracovává připojení k kanálům.
• Obslužná rutina pro otáčení, obvykle zapouzdřená ve třídě robota , která zpracovává konverzační odůvodnění aplikace robota.

V reakci na příchozí zprávu od uživatele volá aplikace metodu aktivity procesu adaptéru, která vytvoří kontext otáčení a otáčení, zavolá jeho middlewarový kanál a potom zavolá obslužnou rutinu otáčení robota.

Aby bylo možné zahájit proaktivní zprávu, musí být aplikace robota schopná přijímat další vstupy. Logika aplikace pro inicializování proaktivní zprávy je mimo rozsah sady SDK. Pro tuto ukázku se kromě standardního koncového bodu zpráv používá koncový bod upozornění k aktivaci proaktivního turnu.

V reakci na požadavek GET na tomto koncovém bodu upozornění aplikace volá metodu pokračování konverzace adaptéru, která se chová podobně jako metoda aktivity procesu. Metoda pokračování konverzace :

• Vezme vhodný odkaz na konverzaci pro uživatele a metodu zpětného volání, která se má použít pro aktivní otáčení.
• Vytvoří aktivitu události a kontext pro proaktivní otáčení.
• Volá kanál middlewaru adaptéru.
• Volá zadanou metodu zpětného volání.
• Kontext otáčení používá odkaz na konverzaci k odeslání všech zpráv uživateli.

Ukázka obsahuje robota, koncový bod zpráv a další koncový bod, který se používá k odesílání proaktivních zpráv uživateli, jak je znázorněno na následujícím obrázku.

Načtení a uložení odkazu na konverzaci

Když se bot Framework Emulator připojí k robotovi, robot obdrží dvě aktivity aktualizace konverzací. V obslužné rutině aktivity aktualizace konverzace robota se odkaz na konverzaci načte a uloží do slovníku, jak je znázorněno níže.

C#

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

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

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

Odkaz na konverzaci obsahuje vlastnost konverzace , která popisuje konverzaci, ve které aktivita existuje. Konverzace obsahuje vlastnost uživatele , která obsahuje seznam uživatelů, kteří se účastní konverzace, a vlastnost adresy URL služby, která označuje, kde se můžou odesílat odpovědi na aktuální aktivitu. K odesílání proaktivních zpráv uživatelům je potřeba platný odkaz na konverzaci. (Pro kanál Teams se adresa URL služby mapuje na regionalizovaný server.)

Poznámka:

V reálném scénáři byste zachovali odkazy na konverzace v databázi místo použití objektu v paměti.

Odeslání proaktivní zprávy

Druhý kontroler, kontroler oznámení , je zodpovědný za odeslání proaktivní zprávy uživateli. K vygenerování proaktivní zprávy používá následující kroky.

1. Načte odkaz na konverzaci, do které chcete odeslat proaktivní zprávu.
2. Zavolá metodu pokračování konverzace adaptéru a poskytne odkaz na konverzaci a delegáta obslužné rutiny otáčení, který se má použít. (Metoda pokračování konverzace vygeneruje kontext turnu pro odkazovanou konverzaci a potom zavolá zadaný delegát obslužné rutiny turn.)
3. V delegátu používá kontext otáčení k odeslání proaktivní zprávy. V tomto případě je delegát definován na kontroleru oznámení a odešle proaktivní zprávu uživateli.

Poznámka:

Každý kanál by měl používat stabilní adresu URL služby, ale adresa URL se může v průběhu času změnit. Další informace o adrese URL služby najdete v oddílech Základní struktura aktivit a adresa URL služby schématu aktivity služby Bot Framework.

Pokud se adresa URL služby změní, odkazy na předchozí konverzaci už nebudou platné a volání pro pokračování konverzace vygenerují chybu nebo výjimku. V takovém případě bude robot muset uživateli získat nový odkaz na konverzaci, aby mohl znovu odesílat proaktivní zprávy.

C#

Controllers\NotifyController .cs

Pokaždé, když se vyžádá stránka s oznámením robota, kontroler oznámení načte odkazy na konverzaci ze slovníku. Kontroler pak použije ContinueConversationAsync a BotCallback metody k odeslání proaktivní zprávy.

[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

Pokaždé, když se vyžádá stránka serveru /api/notify , server načte odkazy na konverzaci ze slovníku. Server pak použije metodu continueConversation k odeslání proaktivní zprávy. Parametrem continueConversation je funkce, která slouží jako obslužná rutina otáčení robota pro tento tah.

    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

Pokaždé, když se vyžádá stránka s oznámením robota, kontroler oznámení načte odkazy na konverzaci ze slovníku. Kontroler pak použije metodu continueConversation k odeslání proaktivní zprávy.

@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

Pokaždé, když se vyžádá stránka s upozorněním robota, server načte odkazy na konverzaci ze slovníku. Server pak použije _send_proactive_message k odeslání proaktivní zprávy.

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

Pokud chcete odeslat proaktivní zprávu, adaptér vyžaduje ID aplikace robota. V produkčním prostředí můžete použít ID aplikace robota. Pokud chcete robota otestovat místně pomocí emulátoru, můžete použít prázdný řetězec ("").

Otestovat robota

1. Pokud jste to ještě neudělali, nainstalujte bot Framework Emulator.
2. Spusťte ukázku místně na svém počítači.
3. Spusťte emulátor a připojte se k robotovi.
4. Načtěte na stránku rozhraní API/notify vašeho robota. Tím se v emulátoru vygeneruje proaktivní zpráva.

Další informace

Požadavky

Než budete moct odeslat proaktivní zprávu, potřebuje robot odkaz na konverzaci. Robot může načíst odkaz na konverzaci z jakékoli aktivity, kterou přijal od uživatele, ale obvykle to vyžaduje, aby uživatel pracoval s robotem alespoň jednou, než robot může odeslat proaktivní zprávu.

Mnoho kanálů zakáže robotovi zasílání zpráv uživateli, pokud uživatel alespoň jednou nesílá robota. Některé kanály umožňují výjimky. Kanál Teams například umožňuje robotovi odeslat proaktivní (nebo 1-on-1) zprávu jednotlivcům v již vytvořené skupinové konverzaci, která obsahuje robota.

Aspekty návrhu

Při implementaci proaktivních zpráv v robotovi neodesílejte několik proaktivních zpráv během krátké doby. Některé kanály vynucují omezení, jak často může robot posílat zprávy uživateli, a zakáže robota, pokud tato omezení porušuje.

V případě nejjednoduššího typu proaktivní zprávy robot protíná zprávu do konverzace, když se aktivuje, bez ohledu na aktuální stav nebo téma konverzace. V tomto scénáři proaktivní zpráva přeruší normální tok konverzace.

Pokud chcete oznámení zpracovávat plynuleji, zvažte další způsoby integrace oznámení do toku konverzace, například nastavení příznaku ve stavu konverzace nebo přidání oznámení do fronty.

O proaktivním otáčení

Metoda pokračování konverzace používá odkaz na konverzaci a obslužnou rutinu zpětného volání pro:

1. Vytvořte odevzdání, ve kterém může aplikace robota odeslat proaktivní zprávu. Adaptér pro tento turn vytvoří event aktivitu s názvem "ContinueConversation".
2. Odešlete průchozí kanál middlewaru adaptéru.
3. Volání obslužné rutiny zpětného volání turn k provedení vlastní logiky.

V ukázce proaktivních zpráv je obslužná rutina zpětného volání definovaná v kontroleru oznámení a odesílá zprávu přímo do konverzace, aniž by se aktivní aktivita odesílala přes normální obslužnou rutinu otáčení robota. Ukázkový kód také nemá přístup k aktivnímu zapnutí nebo aktualizuje stav robota.

Mnoho robotů je stavové a používá stav ke správě konverzace přes několik otočení. Když metoda pokračovat v konverzaci vytvoří kontext otáčení, bude mít k němu přidružený správný stav uživatele a konverzace a můžete integrovat proaktivní převod do logiky robota. Pokud potřebujete logiku robota, abyste si byli vědomi proaktivní zprávy, máte několik možností, jak to udělat. Můžete provádět následující akce:

• Zadejte obslužnou rutinu otáčení robota jako obslužnou rutinu zpětného volání volání. Robot pak obdrží aktivitu události ContinueConversation.
• Pomocí obslužné rutiny zpětného volání volání nejprve přidejte informace do kontextu turn a pak volejte obslužnou rutinu otáčení robota.

V obou těchto případech budete muset navrhnout logiku robota tak, aby zpracovávala proaktivní událost.

Další kroky

Implementace sekvenčního toku konverzace