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 à des stimulations qui ne proviennent pas de l'utilisateur.

Les messages proactifs peuvent être utiles dans différents cas de figure. 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 décrit 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

• L'échantillon du bot de conversation Teams enC#,JavaScript, Java, ou Python.
• Documentation de Microsoft Teams sur l'envoi de messages proactifs.

Remarque

Les kits SDK JavaScript, C# et Python Bot Framework continueront d’être pris en charge. Toutefois, le kit de développement logiciel (SDK) Java est mis hors service avec une prise en charge finale à long terme se terminant en novembre 2023.

Les bots existants créés avec le kit de développement logiciel (SDK) Java continueront de fonctionner.

Pour la nouvelle génération de bots, envisagez d’utiliser Microsoft Copilot Studio et lisez-en plus sur le choix de la solution copilote appropriée.

Pour plus d’informations, consultez Les futures versions de bot.

Prérequis

• Comprendre les concepts de base des bots.
• Une copie de l'échantillon 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 possède quelques couches :

• L'application Web qui peut accepter des requêtes HTTP et prendre spécifiquement en charge un point de terminaison de messagerie.
• Un adaptateur qui gère la connectivité avec les canaux.
• Un gestionnaire du tour, généralement encapsulé dans une classe de bot qui gère le raisonnement de conversation 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, 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 bot doit être en mesure de recevoir d'autres entrées. La logique d'application pour lancer un message proactif se trouve en dehors de l'étendue du kit de développement logiciel (SDK). Pour cet échantillon, 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 poursuite de la conversation :

• 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'échantillon comporte un bot, un point de terminaison des messages et un point de terminaison supplémentaire utilisé pour envoyer des messages proactifs à l'utilisateur, comme le montre 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 comprend une propriété de conversation qui décrit la conversation dans laquelle se trouve l'activité. La conversation comprend une propriété utilisateur qui répertorie les utilisateurs participant à la conversation, et une propriété 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 la chaîne Teams, l'URL du service est mappée à un serveur régionalisé.)

Remarque

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 au à l'utilisateur. Il utilise les étapes suivantes pour générer un message proactif.

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

Remarque

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 la structure d'activité de base et les sections du service URL du schéma d'activité Bot Framework.

Si le service URL 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 devra 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 méthode continueConversation 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.

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

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 bot

1. Si vous ne l'avez pas encore fait, installez 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. Un message proactif est alors généré dans l'émulateur.

Informations supplémentaires

Spécifications

Avant d'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 toute activité 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 empêchent un bot de messagerie d'un utilisateur, sauf si l'utilisateur a envoyé un message au moins une fois au bot. Certains canaux autorisent des exceptions. Par exemple, la chaîne Teams permet à votre bot d'envoyer un message proactif (ou une validation d'information) à des personnes d'une conversation de groupe déjà établie qui inclut le bot.

Considérations sur la conception

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 de la rubrique de conversation. Dans ce scénario, le message proactif interrompt le flux normal de 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.

Informations sur le tour proactif

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

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

Dans l'échantillon de messages proactifs, le gestionnaire de rappel de tour 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 ne permet pas non plus d'accéder à l'état du bot ou de le mettre à jour lors du tour proactif.

De nombreux bots sont avec état et utilisent l'état pour gérer une conversation à plusieurs tours. Lorsque la méthode de conversation continue crée un contexte de tour, le tour aura l'état d'utilisateur et de conversation approprié associé, et vous pouvez intégrer des tournures proactives dans la logique de votre bot. Si vous avez besoin de la logique du bot pour connaître le message proactif, vous avez quelques options pour le faire. Vous pouvez :

• Fournissez le gestionnaire de tour du bot en tant que gestionnaire de rappel de tour. Le bot reçoit ensuite l'activité d'événement « ContinueConversation ».
• Utilisez le gestionnaire de rappel de tour pour ajouter d'abord des informations au contexte de tour, puis appelez le gestionnaire de tour du bot.

Dans ces 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