Envoyer des notifications proactives aux utilisateurs

S’APPLIQUE À : SDK v4

En règle générale, un bot envoie un message à un utilisateur directement en réponse à la réception d’un message de l’utilisateur. Parfois, un bot peut avoir besoin d’envoyer un message proactif, un message en réponse à un stimulus qui ne provient pas de l’utilisateur.

Les messages proactifs peuvent être utiles dans différents scénarios. Par exemple, si l’utilisateur a précédemment demandé au bot de surveiller le prix d’un produit, le bot peut alerter l’utilisateur dès que le prix du produit diminue de 20 %. En outre, si un bot a besoin de temps pour compiler une réponse à la question de l’utilisateur, il peut informer l’utilisateur de ce délai et autoriser la conversation à se poursuivre dans l’intervalle. Puis, dès que le bot a terminé de compiler la réponse à la question, il partage cette information avec l’utilisateur.

Cet article fournit des informations sur les messages proactifs pour les bots en général. Pour plus d’informations sur les messages proactifs dans Microsoft Teams, consultez

• Exemple de bot de conversation Teams en C#, JavaScript, Java ou Python.
• La documentation Microsoft Teams sur l’envoi de messages proactifs.

Notes

Les Kits de développement logiciel (SDK) Python et Java bot Framework sont mis hors service avec une prise en charge finale à long terme qui se termine en novembre 2023. Seuls les correctifs de sécurité et de bogues critiques au sein de ce référentiel seront entrepris. Les bots existants créés avec ces SDK continueront de fonctionner.

Pour le développement de nouveaux bots, envisagez d’utiliser Power Virtual Agents. Pour plus d’informations, consultez L’avenir de la génération de bots.

Prérequis

• Comprendre les concepts de base des bots.
• Copie de l’exemple de messages proactifs en C#, JavaScript, Java ou Python. L’exemple sert à expliquer la messagerie proactive dans cet article.

À propos de l’exemple proactif

En général, un bot en tant qu’application comporte quelques couches :

• L’application web qui peut accepter les requêtes HTTP et prend spécifiquement en charge un point de terminaison de messagerie.
• Adaptateur qui gère la connectivité avec les canaux.
• Gestionnaire pour le tour, généralement encapsulé dans une classe de bot qui gère le raisonnement conversationnel de l’application bot.

En réponse à un message entrant de l’utilisateur, l’application appelle la méthode d’activité de processus de l’adaptateur, ce qui crée un contexte de tour et de tour, appelle son pipeline d’intergiciels, puis appelle le gestionnaire de tour du bot.

Pour lancer un message proactif, l’application de bot doit être en mesure de recevoir d’autres entrées. La logique d’application pour lancer un message proactif est en dehors de l’étendue du Kit de développement logiciel (SDK). Pour cet exemple, un point de terminaison de notification , en plus d’un point de terminaison de messages standard, est utilisé pour déclencher le tour proactif.

En réponse à une demande GET sur ce point de terminaison de notification, l’application appelle la méthode de conversation continue de l’adaptateur, qui se comporte de la même façon que la méthode d’activité de processus . La méthode de conversation continue :

• Prend une référence de conversation appropriée pour l’utilisateur et la méthode de rappel à utiliser pour le tour proactif.
• Crée une activité d’événement et un contexte de tour pour le tour proactif.
• Appelle le pipeline d’intergiciel de l’adaptateur.
• Appelle la méthode de rappel fournie.
• Le contexte de tour utilise la référence de conversation pour envoyer des messages à l’utilisateur.

L’exemple a un bot, un point de terminaison de messages et un point de terminaison supplémentaire qui est utilisé pour envoyer des messages proactifs à l’utilisateur, comme illustré dans l’illustration suivante.

Récupérer et stocker la référence de conversation

Lorsque le Bot Framework Emulator se connecte au bot, celui-ci reçoit deux activités de mise à jour de conversation. Dans le gestionnaire d’activité de mise à jour de conversation du bot, la référence de conversation est récupérée et stockée dans un dictionnaire, comme indiqué ci-dessous.

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

La référence de conversation inclut une propriété de conversation qui décrit la conversation dans laquelle l’activité existe. La conversation inclut une propriété utilisateur qui répertorie les utilisateurs participant à la conversation et une propriété d’URL de service qui indique où les réponses à l’activité en cours peuvent être envoyées. Une référence de conversation valide est nécessaire pour envoyer des messages proactifs aux utilisateurs. (Pour le canal Teams, l’URL du service est mappée à un serveur régionalisé.)

Notes

Dans un scénario réel, vous conserveriez les références de conversation dans une base de données au lieu d’utiliser un objet en mémoire.

Envoyer un message proactif

Le deuxième contrôleur, le contrôleur de notification , est chargé d’envoyer le message proactif à l’utilisateur. Il utilise les étapes suivantes pour générer un message proactif.

1. Récupère la référence de la conversation à laquelle envoyer le message proactif.
2. Appelle la méthode continue de conversation de l’adaptateur, en fournissant la référence de conversation et le délégué du gestionnaire de tour à utiliser. (La méthode continue conversation génère un contexte de tour pour la conversation référencée, puis appelle le délégué de gestionnaire de tour spécifié.)
3. Dans le délégué, utilise le contexte de tour pour envoyer le message proactif. Ici, le délégué est défini sur le contrôleur de notification et il envoie le message proactif à l’utilisateur.

Notes

Bien que chaque canal utilise une URL de service stable, l’URL peut changer au fil du temps. Pour plus d’informations sur l’URL du service, consultez les sections Structure de l’activité de base et URL de service du schéma d’activité Bot Framework.

Si l’URL du service change, les références de conversation précédentes ne sont plus valides et les appels pour poursuivre la conversation génèrent une erreur ou une exception. Dans ce cas, votre bot doit acquérir une nouvelle référence de conversation pour l’utilisateur avant de pouvoir envoyer à nouveau des messages proactifs.

C#

Controllers\NotifyController.cs

Chaque fois que la page de notification du bot est demandée, le contrôleur de notification récupère les références de conversation à partir du dictionnaire. Le contrôleur utilise ensuite les méthodes ContinueConversationAsync et BotCallback pour envoyer le message proactif.

[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

Chaque fois que la page /api/notify du serveur est demandée, le serveur récupère les références de conversation à partir du dictionnaire. Le serveur utilise ensuite la méthode continueConversation pour envoyer le message proactif. Le paramètre pour continueConversation est une fonction qui sert de gestionnaire de tours au bot pour ce tour.

    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

Chaque fois que la page de notification du bot est demandée, le contrôleur de notification récupère les références de conversation à partir du dictionnaire. Le contrôleur utilise ensuite la continueConversation méthode pour envoyer le message proactif.

@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

Chaque fois que la page de notification du bot est demandée, le serveur récupère les références de conversation dans le dictionnaire. Le serveur utilise ensuite _send_proactive_message pour envoyer le message proactif.

# Send a message to all conversation members.
# This uses the shared Dictionary that the Bot adds conversation references to.
async def _send_proactive_message():
    for conversation_reference in CONVERSATION_REFERENCES.values():
        await ADAPTER.continue_conversation(
            conversation_reference,
            lambda turn_context: turn_context.send_activity("proactive hello"),
            APP_ID,
        )

Pour envoyer un message proactif, l’adaptateur a besoin d’un ID d’application pour le bot. Dans un environnement de production, vous pouvez utiliser l’ID d’application du bot. Pour tester le bot localement avec l’émulateur, vous pouvez utiliser la chaîne vide («  »).

Tester votre robot

1. Si vous ne l’avez pas déjà fait, installez le Bot Framework Emulator.
2. Exécutez l’exemple en local sur votre machine.
3. Démarrez l’émulateur et connectez-vous à votre bot.
4. Chargez à la page de notification/d’api de votre bot. Cela génère un message proactif dans l’émulateur.

Informations supplémentaires

Configuration requise

Avant de pouvoir envoyer un message proactif, votre bot a besoin d’une référence de conversation. Votre bot peut récupérer la référence de conversation à partir de n’importe quelle activité qu’il a reçue de l’utilisateur, mais cela nécessite généralement que l’utilisateur interagisse avec le bot au moins une fois avant que le bot puisse envoyer un message proactif.

De nombreux canaux interdisent à un bot d’envoyer des messages à un utilisateur, sauf si l’utilisateur a envoyé un message au bot au moins une fois. Certains canaux autorisent des exceptions. Par exemple, le canal Teams permet à votre bot d’envoyer un message proactif (ou 1-sur-1) aux personnes dans une conversation de groupe déjà établie qui inclut le bot.

Éléments de conception à prendre en considération

Lors de l’implémentation de messages proactifs dans votre bot, n’envoyez pas plusieurs messages proactifs dans un même court laps de temps. Certains canaux appliquent des restrictions concernant la fréquence à laquelle un bot peut envoyer des messages à l’utilisateur, et désactivent le bot si ce dernier enfreint ces restrictions.

Pour le type de message proactif le plus simple, le bot interjecte le message dans la conversation lorsqu’il est déclenché, sans tenir compte de l’état actuel ou du sujet de la conversation. Dans ce scénario, le message proactif interrompt le flux normal de la conversation.

Pour gérer plus facilement les notifications, pensez à d’autres méthodes pour intégrer la notification dans le flux de messages. Par exemple, vous pouvez définir un indicateur dans l’état de la conversation ou ajouter la notification à une file d’attente.

À propos du virage proactif

La méthode continue de la conversation utilise la référence de conversation et un gestionnaire de rappel de turn pour :

1. Créez un tour dans lequel l’application de bot peut envoyer le message proactif. L’adaptateur crée une event activité pour ce tour, avec son nom défini sur « ContinueConversation ».
2. Envoyez le tour via le pipeline d’intergiciel de l’adaptateur.
3. Appelez le gestionnaire de rappel de tour pour effectuer une logique personnalisée.

Dans l’exemple de messages proactifs , le gestionnaire de rappel de retour est défini dans le contrôleur de notification et envoie le message directement à la conversation, sans envoyer l’activité proactive via le gestionnaire de tour normal du bot. L’exemple de code n’accède pas non plus ni ne met à jour l’état du bot sur le tour proactif.

De nombreux bots sont avec état et utilisent l’état pour gérer une conversation en plusieurs tours. Lorsque la méthode de conversation continue crée un contexte de tour, l’utilisateur et l’état de conversation appropriés sont associés au tour, et vous pouvez intégrer des tours proactifs dans la logique de votre bot. Si vous avez besoin que la logique du bot connaisse le message proactif, vous avez quelques options pour le faire. Vous pouvez :

• Indiquez le gestionnaire de tour du bot comme gestionnaire de rappel de retour. Le bot recevra ensuite l’activité d’événement « ContinueConversation ».
• Utilisez d’abord le gestionnaire de rappel de tour pour ajouter des informations au contexte de tour, puis appelez le gestionnaire de tour du bot.

Dans les deux cas, vous devez concevoir votre logique de bot pour gérer l’événement proactif.

Étapes suivantes

Implémenter des flux de conversation séquentiels