Proactieve meldingen verzenden naar gebruikers

VAN TOEPASSING OP: SDK v4

Normaal gesproken verzendt een bot een bericht rechtstreeks naar een gebruiker als reactie op het ontvangen van een bericht van de gebruiker. Soms moet een bot mogelijk een proactief bericht verzenden, een bericht als reactie op prikkels die niet afkomstig zijn van de gebruiker.

Proactieve berichten kunnen handig zijn in verschillende scenario's. Als de gebruiker de bot bijvoorbeeld eerder heeft gevraagd om de prijs van een product te controleren, kan de bot de gebruiker waarschuwen als de prijs van het product met 20% is gedaald. Of als een bot enige tijd nodig heeft om een antwoord op de vraag van de gebruiker te compileren, kan het de gebruiker informeren over de vertraging en het gesprek in de tussentijd toestaan. Wanneer de bot klaar is met het compileren van het antwoord op de vraag, wordt die informatie met de gebruiker gedeeld.

In dit artikel wordt informatie behandeld over proactieve berichten voor bots in het algemeen. Zie voor meer informatie over proactieve berichten in Microsoft Teams

• Het voorbeeld van de Teams-gespreksbot in C#, JavaScript, Java of Python.
• De documentatie van Microsoft Teams over het verzenden van proactieve berichten.

Notitie

De Sdk's voor Bot Framework JavaScript, C# en Python blijven ondersteund, maar de Java SDK wordt buiten gebruik gesteld met definitieve langetermijnondersteuning die eindigt op november 2023.

Bestaande bots die zijn gebouwd met de Java SDK blijven functioneren.

Voor het bouwen van nieuwe bots kunt u Microsoft Copilot Studio gebruiken en lezen over het kiezen van de juiste copilot-oplossing.

Zie De toekomst van botbouw voor meer informatie.

Vereisten

• Basisbeginselen van bot begrijpen.
• Een kopie van het proactieve berichtenvoorbeeld in C#, JavaScript, Java of Python. Het voorbeeld wordt gebruikt om proactieve berichten in dit artikel uit te leggen.

Over het proactieve voorbeeld

Over het algemeen heeft een bot als een toepassing een aantal lagen:

• De webtoepassing die HTTP-aanvragen kan accepteren en specifiek ondersteuning biedt voor een berichteindpunt.
• Een adapter die de connectiviteit met de kanalen afhandelt.
• Een handler voor de beurt, meestal ingekapseld in een botklasse die de gespreksredenering voor de bot-app afhandelt.

Als reactie op een binnenkomend bericht van de gebruiker roept de app de procesactiviteitsmethode van de adapter aan, waarmee een turn-and-turncontext wordt gemaakt, de middleware-pijplijn wordt aangeroepen en vervolgens de beurthandler van de bot wordt aangeroepen.

Als u een proactief bericht wilt initiëren, moet de bottoepassing andere invoer kunnen ontvangen. De toepassingslogica voor het initiëren van een proactief bericht valt buiten het bereik van de SDK. Voor dit voorbeeld wordt een meldingseindpunt, naast een standaardberichteindpunt, gebruikt om de proactieve draai te activeren.

Als reactie op een GET-aanvraag op dit meldingseindpunt roept de app de continue gespreksmethode van de adapter aan, die zich op dezelfde manier gedraagt als de procesactiviteitsmethode. De continue gespreksmethode :

• Neemt een geschikte gespreksreferentie voor de gebruiker en de callback-methode om te gebruiken voor de proactieve beurt.
• Hiermee maakt u een gebeurtenisactiviteit en beurtcontext voor de proactieve beurt.
• Roept de middlewarepijplijn van de adapter aan.
• Roept de opgegeven callback-methode aan.
• De beurtcontext maakt gebruik van de gespreksreferentie om berichten naar de gebruiker te verzenden.

Het voorbeeld heeft een bot, een eindpunt voor berichten en een extra eindpunt dat wordt gebruikt om proactieve berichten naar de gebruiker te verzenden, zoals wordt weergegeven in de volgende afbeelding.

De gespreksreferentie ophalen en opslaan

Wanneer de Bot Framework Emulator verbinding maakt met de bot, ontvangt de bot twee gespreksupdateactiviteiten. In de activiteitshandler voor gespreksupdates van de bot wordt de gespreksverwijzing opgehaald en opgeslagen in een woordenlijst, zoals hieronder wordt weergegeven.

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

@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

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

De gespreksverwijzing bevat een gesprekseigenschap waarin het gesprek wordt beschreven waarin de activiteit bestaat. Het gesprek bevat een gebruikerseigenschap waarin de gebruikers worden vermeld die deelnemen aan het gesprek en een service-URL-eigenschap die aangeeft waar antwoorden op de huidige activiteit kunnen worden verzonden. Er is een geldige gespreksreferentie nodig om proactieve berichten naar gebruikers te verzenden. (Voor het Teams-kanaal wordt de service-URL toegewezen aan een ge regionaliseerde server.)

Notitie

In een praktijkscenario kunt u gespreksverwijzingen in een database behouden in plaats van een object in het geheugen te gebruiken.

Een proactief bericht verzenden

De tweede controller, de meldingscontroller , is verantwoordelijk voor het verzenden van het proactieve bericht naar de gebruiker. Hierbij worden de volgende stappen gebruikt om een proactief bericht te genereren.

1. Haalt de verwijzing op voor het gesprek waarnaar het proactieve bericht moet worden verzonden.
2. Roept de continue gespreksmethode van de adapter aan, zodat de gespreksverwijzing en de gemachtigde van de turnhandler die moet worden gebruikt. (De continue gespreksmethode genereert een turncontext voor het gesprek waarnaar wordt verwezen en roept vervolgens de opgegeven gemachtigde voor de turnhandler aan.)
3. In de gedelegeerde wordt de beurtcontext gebruikt om het proactieve bericht te verzenden. Hier wordt de gemachtigde gedefinieerd op de meldingscontroller en wordt het proactieve bericht naar de gebruiker verzonden.

Notitie

Hoewel elk kanaal een stabiele service-URL moet gebruiken, kan de URL na verloop van tijd veranderen. Zie de secties Basisactiviteitsstructuur en Service-URL van het Bot Framework-activiteitsschema voor meer informatie over de service-URL .

Als de service-URL wordt gewijzigd, zijn eerdere gespreksverwijzingen niet meer geldig en worden oproepen om door te gaan met gesprekken een fout of uitzondering gegenereerd. In dit geval moet uw bot een nieuwe gespreksverwijzing voor de gebruiker verkrijgen voordat deze proactieve berichten opnieuw kan verzenden.

C#

Controllers\NotifyController .cs

Telkens wanneer de meldingspagina van de bot wordt aangevraagd, haalt de controller de gespreksverwijzingen op uit de woordenlijst. De controller gebruikt vervolgens de ContinueConversationAsync en BotCallback methoden om het proactieve bericht te verzenden.

[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

Telkens wanneer de pagina van /api/notify de server wordt aangevraagd, haalt de server de gespreksverwijzingen op uit de woordenlijst. De server gebruikt vervolgens de continueConversation methode om het proactieve bericht te verzenden. De parameter aan continueConversation is een functie die fungeert als de turnhandler van de bot voor deze beurt.

    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

Telkens wanneer de meldingspagina van de bot wordt aangevraagd, haalt de controller de gespreksverwijzingen op uit de woordenlijst. De controller gebruikt vervolgens de continueConversation methode om het proactieve bericht te verzenden.

@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

Telkens wanneer de meldingspagina van de bot wordt aangevraagd, haalt de server de gespreksverwijzingen op uit de woordenlijst. De server gebruikt vervolgens de _send_proactive_message server om het proactieve bericht te verzenden.

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

Voor het verzenden van een proactief bericht heeft de adapter een app-id voor de bot nodig. In een productieomgeving kunt u de app-id van de bot gebruiken. Als u de bot lokaal wilt testen met de emulator, kunt u de lege tekenreeks ("").

Uw bot testen

1. Als u dit nog niet hebt gedaan, installeert u de Bot Framework Emulator.
2. Voer het voorbeeld lokaal uit op uw computer.
3. Start de emulator en maak verbinding met uw bot.
4. Laad de api/meldingspagina van uw bot. Hiermee wordt een proactief bericht gegenereerd in de emulator.

Aanvullende informatie

Vereisten

Voordat u een proactief bericht kunt verzenden, heeft uw bot een gespreksreferentie nodig. Uw bot kan de gespreksverwijzing ophalen uit elke activiteit die de gebruiker heeft ontvangen, maar dit vereist doorgaans dat de gebruiker ten minste één keer met de bot communiceert voordat de bot een proactief bericht kan verzenden.

Veel kanalen verbieden een bot om een gebruiker te berichten sturen, tenzij de gebruiker de bot ten minste één keer heeft geberichtd. Sommige kanalen staan uitzonderingen toe. Met het Teams-kanaal kan uw bot bijvoorbeeld een proactief (of 1-op-1) bericht verzenden naar personen in een reeds tot stand gebracht groepsgesprek met de bot.

Ontwerpoverwegingen

Wanneer u proactieve berichten in uw bot implementeert, moet u niet binnen een korte tijd meerdere proactieve berichten verzenden. Sommige kanalen dwingen beperkingen af voor hoe vaak een bot berichten naar de gebruiker kan verzenden en schakelt de bot uit als deze beperkingen schendt.

Voor het eenvoudigste type proactief bericht ondervoegt de bot het bericht in het gesprek wanneer het wordt geactiveerd, zonder rekening te houden met de huidige status of het huidige gespreksonderwerp. In dit scenario onderbreekt het proactieve bericht de normale gespreksstroom.

Als u meldingen soepeler wilt afhandelen, kunt u andere manieren overwegen om de melding te integreren in de gespreksstroom, zoals het instellen van een vlag in de gespreksstatus of het toevoegen van de melding aan een wachtrij.

Over de proactieve draai

De continue gespreksmethode maakt gebruik van de gespreksreferentie en een callbackhandler om het volgende te doen:

1. Maak een beurt waarin de bottoepassing het proactieve bericht kan verzenden. De adapter maakt een event activiteit voor deze beurt, waarbij de naam is ingesteld op ContinueConversation.
2. Verzend de draai door de middlewarepijplijn van de adapter.
3. Roep de callback-handler aan om aangepaste logica uit te voeren.

In het voorbeeld van proactieve berichten wordt de callbackhandler in de meldingscontroller gedefinieerd en wordt het bericht rechtstreeks naar het gesprek verzonden, zonder dat de proactieve activiteit via de normale draaihandler van de bot wordt verzonden. De voorbeeldcode heeft ook geen toegang tot de status van de bot of werkt deze bij op de proactieve beurt.

Veel bots zijn stateful en gebruiken de status om een gesprek over meerdere beurten te beheren. Wanneer de continue gespreksmethode een turncontext maakt, heeft de beurt de juiste gebruikers- en gespreksstatus eraan gekoppeld en kunt u proactieve omzetten integreren in de logica van uw bot. Als u de botlogica nodig hebt om op de hoogte te zijn van het proactieve bericht, hebt u een aantal opties om dit te doen. U kunt:

• Geef de turnhandler van de bot op als de callback-handler voor turnback. De bot ontvangt vervolgens de gebeurtenisactiviteit ContinueConversation.
• Gebruik de callbackhandler om eerst informatie toe te voegen aan de turncontext en roep vervolgens de turn-handler van de bot aan.

In beide gevallen moet u uw botlogica ontwerpen om de proactieve gebeurtenis af te handelen.

Volgende stappen

Sequentiële gespreksstroom implementeren