Messages proactifs

  • Article

Importante

Les exemples de code de cette section sont basés sur la version 4.6 et les versions ultérieures du Kit de développement logiciel (SDK) Bot Framework. Si vous recherchez de la documentation pour les versions antérieures, consultez la section bots - Kit de développement logiciel (SDK) v3 dans le dossier Kits de développement logiciel (SDK) hérités de la documentation.

Un message proactif est un message envoyé par un bot qui ne répond pas à la demande d’un utilisateur. Ce message peut inclure du contenu, par exemple :

  • Les messages de bienvenue
  • Notifications
  • Messages planifiés

Importante

Pour envoyer un message proactif à un utilisateur, à une conversation de groupe ou à une équipe, votre bot doit disposer de l’accès requis pour envoyer le message. Pour une conversation de groupe ou d’équipe, l’application contenant votre bot doit d’abord être installée à cet emplacement.

Vous pouvez installer de manière proactive votre application à l’aide de Microsoft Graph dans une équipe, si nécessaire, ou utiliser une stratégie d’application personnalisée pour installer une application dans vos équipes et pour les utilisateurs de organization. Dans certains cas, vous devez installer votre application de manière proactive à l’aide de Graph. Pour qu’un utilisateur reçoive des messages proactifs, installez l’application pour l’utilisateur ou faites-le partie d’une équipe dans laquelle l’application est installée.

L’envoi d’un message proactif est différent de l’envoi d’un message classique. Il n’existe aucun turnContext actif à utiliser pour la réponse. Vous devez créer la conversation avant l’envoi du message. Par exemple, une nouvelle conversation en face à face ou un nouveau fil de conversation dans un canal. Vous ne pouvez pas créer une conversation de groupe ou un nouveau canal dans une équipe à l’aide d’une messagerie proactive.

Pour envoyer un message proactif, suivez ces étapes :

  1. Si nécessaire, obtenez l’ID d’utilisateur, l’ID d’utilisateur, l’ID d’équipe ou l’ID de canal Microsoft Entra.
  2. Créez la conversation (si nécessaire).
  3. Obtenez l’identification de la conversation.
  4. Envoyez le message.

Les extraits de code de la section exemples doivent créer une conversation en face à face. Pour obtenir des liens vers des exemples de conversations en tête-à-tête et de messages de groupe ou de canaux, consultez exemple de code. Pour utiliser efficacement les messages proactifs, consultez les meilleures pratiques en matière de messagerie proactive.

Obtenir l’ID d’utilisateur, l’ID utilisateur, l’ID d’équipe ou l’ID de canal Microsoft Entra

Vous pouvez créer une conversation avec un utilisateur ou un thread de conversation dans un canal et vous devez disposer de l’ID correct. Vous pouvez recevoir ou récupérer cet ID de l’une des manières suivantes :

  • Lorsque votre application est installée dans un contexte particulier, vous recevez une onMembersAdded activité.
  • Lorsqu’un nouvel utilisateur est ajouté à un contexte où votre application est installée, vous recevez une onMembersAddedactivité.
  • Chaque événement reçu par le bot contient les informations requises, que vous pouvez obtenir à partir du contexte du bot (objet TurnContext).
  • Vous pouvez récupérer la liste des canaux d’une équipe où votre application est installée.
  • Vous pouvez récupérer la liste des membres d’une équipe où votre application est installée.

Quelle que soit la façon dont vous obtenez les informations, stockez le tenantId , puis stockez le userIdou channelId pour créer une conversation. Vous pouvez également utiliser le teamId pour créer un thread de conversation dans le canal général ou par défaut d’une équipe. Vérifiez que le bot est installé dans l’équipe avant de pouvoir envoyer un message proactif à un canal.

  • Le aadObjectId est propre à l’utilisateur et peut être récupéré à l’aide de l’API graphe pour créer une conversation dans une conversation personnelle. Vérifiez que le bot est installé dans l’étendue personnelle avant de pouvoir envoyer un message proactif. Si le bot n’est pas installé dans une étendue personnelle lors de l’envoi d’un message proactif à l’aide de aadObjectId, le bot retourne une 403 erreur avec ForbiddenOperationException un message.

  • Le userId est propre à votre identification de bot et à un utilisateur particulier. Vous ne pouvez pas réutiliser le userId entre les bots.

  • Le channelId est global.

Créez la conversation, une fois que vous avez les informations de l’utilisateur ou du canal.

Remarque

L’envoi de messages proactifs à l’aide de aadObjectId est pris en charge uniquement dans l’étendue personnelle.

Créer la conversation

Vous pouvez créer la conversation si elle n’existe pas ou si vous ne connaissez pas .conversationId Créez la conversation une seule fois et stockez la valeur ou l’objet conversationIdconversationReference .

Pour créer la conversation, vous avez besoin de aadObjectId ou userId, tenantIdet serviceUrl.

Pour serviceUrl, utilisez la valeur d’une activité entrante déclenchant le flux ou l’une des URL du service global. Si n’est serviceUrl pas disponible à partir d’une activité entrante déclenchant le scénario proactif, utilisez les points de terminaison d’URL globaux suivants :

  • Public: https://smba.trafficmanager.net/teams/
  • GCC: https://smba.infra.gcc.teams.microsoft.com/teams
  • GCCH : https://smba.infra.gov.teams.microsoft.us/teams
  • DOD: https://smba.infra.dod.teams.microsoft.us/teams

Pour obtenir un exemple de code, consultez l’appel CreateConversationAsync dans l’exemple.

Vous pouvez obtenir la conversation lorsque l’application est installée pour la première fois. Une fois la conversation créée, obtenez l’ID de conversation. conversationId est disponible dans les événements de mise à jour de conversation.

L’ID de conversation est unique pour chaque bot au sein d’un canal spécifique, même dans un environnement multilocataire. Cet ID garantit que les messages du bot sont dirigés vers le canal approprié et ne s’interrompent pas avec d’autres bots ou canaux au sein d’une même organisation ou d’une organisation différente.

Si vous n’avez pas le conversationId, vous pouvez installer votre application de manière proactive à l’aide de Graph pour obtenir le conversationId.

Obtenir l’identification de la conversation

Utilisez l’objet conversationReference ou conversationId et tenantId pour envoyer le message. Vous pouvez obtenir cette identification en créant la conversation ou en la stockant à partir de n’importe quelle activité vous étant envoyée à partir de ce contexte. Stockez cette identification pour référence.

Une fois les informations d’adresse appropriées reçues, vous pouvez envoyer votre message.

Envoyer le message

Maintenant que vous avez les bonnes informations relatives à l’adresse, vous pouvez envoyer votre message. Si vous utilisez le Kit de développement logiciel (SDK), vous devez utiliser la méthode continueConversation, ainsi que conversationId et tenantId pour effectuer un appel d’API direct. Pour envoyer votre message, définissez .conversationParameters Consultez la section exemples ou utilisez l’un des exemples répertoriés dans la section exemple de code.

Remarque

Teams ne prend pas en charge l’envoi de messages proactifs à l’aide de l’e-mail ou du nom d’utilisateur principal (UPN).

Maintenant que vous avez envoyé le message proactif, vous devez suivre ces meilleures pratiques lors de l’envoi de messages proactifs pour améliorer l’échange d’informations entre les utilisateurs et le bot.

Visionnez la vidéo suivante pour découvrir comment envoyer des messages proactifs à partir de bots :



Comprendre qui a bloqué, désactivé ou désinstallé un bot

En tant que développeur, vous pouvez créer un rapport pour comprendre quels utilisateurs de votre organization avez bloqué, désactivé ou désinstallé un bot. Ces informations peuvent aider les administrateurs de votre organization à diffuser des messages à l’échelle de l’organisation ou à piloter l’utilisation de l’application.

À l’aide de Teams, vous pouvez envoyer un message proactif au bot pour vérifier si un utilisateur a bloqué ou désinstallé un bot. Si le bot est bloqué ou désinstallé, Teams retourne un 403 code de réponse avec un subCode: MessageWritesBlocked. Cette réponse indique que le message envoyé par le bot n’est pas remis à l’utilisateur.

Le code de réponse est envoyé par utilisateur et inclut l’identité de l’utilisateur. Vous pouvez compiler les codes de réponse de chaque utilisateur avec son identité pour créer un rapport de tous les utilisateurs qui ont bloqué le bot.

Voici un exemple de code de réponse 403.


HTTP/1.1 403 Forbidden

Cache-Control: no-store, must-revalidate, no-cache

 Pragma: no-cache

 Content-Length: 196

 Content-Type: application/json; charset=utf-8

 Server: Microsoft-HTTPAPI/2.0

 Strict-Transport-Security: max-age=31536000; includeSubDomains

 MS-CV: NXZpLk030UGsuHjPdwyhLw.5.0

 ContextId: tcid=0,server=msgapi-canary-eus2-0,cv=NXZpLk030UGsuHjPdwyhLw.5.0

 Date: Tue, 29 Mar 2022 17:34:33 GMT

{"errorCode":209,"message":"{\r\n  \"subCode\": \"MessageWritesBlocked\",\r\n  \"details\": \"Thread is blocked from message writes.\",\r\n  \"errorCode\": null,\r\n  \"errorSubCode\": null\r\n}"}

Meilleures pratiques en matière de messagerie proactive

L’envoi de messages proactifs aux utilisateurs constitue un moyen de communication efficace avec vos utilisateurs. Toutefois, du point de vue des utilisateurs, le message s’affiche de manière spontanée. Lorsqu’il y a un message de bienvenue, il s’agira de leur première interaction avec votre application. Il est important d’utiliser cette fonctionnalité et de fournir des informations complètes à l’utilisateur pour comprendre l’objectif de ce message.

Les messages de bienvenue

Lorsque la messagerie proactive est utilisée pour envoyer un message de bienvenue à un utilisateur, il n’existe aucun contexte pour la raison pour laquelle l’utilisateur reçoit le message. En outre, il s’agit de la première interaction de l’utilisateur avec votre application. C’est l’opportunité de faire une bonne première impression. Une bonne expérience utilisateur garantit une meilleure adoption de l’application. Des messages de bienvenue médiocres peuvent amener les utilisateurs à bloquer votre application. Écrivez un message de bienvenue clair et effectuez une itération sur le message d’accueil s’il n’a pas l’effet souhaité.

Un bon message de bienvenue peut inclure les éléments suivants :

  • Raison du message : l’utilisateur doit savoir pourquoi il reçoit le message. Si votre robot a été installé dans un canal et que vous avez envoyé un message de bienvenue à tous les utilisateurs, faites-leur savoir dans quel canal il a été installé et qui l'a installé.

  • Votre offre : les utilisateurs doivent être en mesure d’identifier ce qu’ils peuvent faire avec votre application et la valeur que vous pouvez leur apporter.

  • Étapes suivantes : les utilisateurs doivent comprendre les étapes suivantes. Par exemple, invitez les utilisateurs à essayer une commande ou à interagir avec votre application.

Les messages de notification

Pour envoyer des notifications à l’aide d’une messagerie proactive, vérifiez que vos utilisateurs ont un chemin d’accès clair pour prendre des mesures communes basées sur votre notification. Veillez à ce que les utilisateurs comprennent clairement pourquoi ils ont reçu une notification. Les messages de notification corrects incluent généralement les éléments suivants :

  • Que s'est-il passé ? Une indication claire de ce qui a causé la réception de la notification.

  • Quel a été le résultat? Il doit être clair et indiquer quel élément est mis à jour pour recevoir la notification.

  • Qui ou ce qui l’a déclenché? Qui ou qui a pris des mesures, ce qui a provoqué l’envoi de la notification.

  • Que peuvent faire les utilisateurs en réponse? Faciliter l’action de vos utilisateurs en fonction de vos notifications

  • Comment les utilisateurs peuvent-ils refuser? Vous devez fournir un chemin d’accès permettant aux utilisateurs de refuser d’autres notifications.

Pour envoyer des messages à un grand groupe d’utilisateurs, par exemple à votre organisation, installez votre application de manière proactive en utilisation Graph.

Messages planifiés

Lorsque vous utilisez une messagerie proactive pour envoyer des messages planifiés aux utilisateurs, veillez à ce que votre fuseau horaire soit défini selon leur fuseau horaire. Cela garantit une remise des messages aux utilisateurs au moment pertinent. Les messages planifiés incluent généralement :

  • Pourquoi l’utilisateur reçoit-il le message? Pour permettre aux utilisateurs de comprendre facilement la raison pour laquelle ils reçoivent le message

  • Que peut faire l’utilisateur ensuite? Les utilisateurs peuvent prendre les mesures nécessaires en fonction du contenu du message.

Installer votre application de manière proactive en utilisant Graph

Envoyez de manière proactive un message aux utilisateurs qui n’ont pas précédemment installé ou interagi avec votre application. Par exemple, vous souhaitez utiliser le communicateur d’entreprise pour envoyer des messages à l’échelle de votre organisation. Dans ce cas, vous pouvez utiliser l’API Graph pour installer de manière proactive votre application pour vos utilisateurs. Mettez en cache les valeurs nécessaires à partir de l’événement conversationUpdate que votre application reçoit lors de l’installation.

Vous pouvez uniquement installer des applications qui se trouvent dans votre catalogue d’applications organisationnelle ou dans le Microsoft Teams Store.

Voir installer des applications pour les utilisateurs dans la documentation Graph et installation et messagerie proactive des bots dans Teams avec Graph. Il existe également un exemple .NET Framework Microsoft sur la plateforme GitHub.

Exemples

Veillez à vous authentifier et à disposer d’un jeton du porteur avant de créer une conversation à l’aide de l’API REST. Voici l’API REST pour créer une conversation dans différents contextes :

  • API REST pour créer une conversation dans une conversation en face à face.

  • API REST pour créer une conversation dans un canal.

  • API REST pour mettre à jour le message dans la conversation : pour mettre à jour une activité existante au sein d’une conversation, incluez conversationId et activityId dans le point de terminaison de la requête. Pour effectuer ce scénario, vous devez mettre en cache l’ID d’activité retourné par l’appel de publication d’origine.

    PUT {Service URL of your bot}/v3/conversations/{conversationId}/activities/{activityId}

    
{
    "type": "message",
    "text": "This message has been updated"
}

    Pour mettre à jour une activité existante dans une conversation, incluez les conversationId et activityId dans le point de terminaison de la requête. Pour effectuer ce scénario, vous devez mettre en cache le activity ID retourné par l’appel post-appel d’origine. Si l’appel réussit, l’API retourne l’objet de réponse suivant.

    {
    "id": "{{activityID}}"
}

Échantillons

Le code suivant indique comment envoyer des messages proactifs :

[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)
        {
            var newReference = new ConversationReference()
            {
                Bot = new ChannelAccount()
                {
                    Id = conversationReference.Bot.Id
                },
                Conversation = new ConversationAccount()
                {
                    Id = conversationReference.Conversation.Id
                },
                ServiceUrl = conversationReference.ServiceUrl,
            };

            // Sends a proactive message from the bot to a conversation.
            await ((BotAdapter)_adapter).ContinueConversationAsync(_appId, newReference, 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)
    {
        // If you encounter permission-related errors when sending this message, see
        // https://learn.microsoft.com/en-us/azure/bot-service/bot-builder-howto-proactive-message?view=azure-bot-service-4.0&tabs=csharp#avoiding-401-unauthorized-errors
        // Sends an activity to the sender of the incoming activity.
        await turnContext.SendActivityAsync("proactive hello");
    }
}

Exemple d’extrait de code pour illustrer la création d’une référence de conversation.

 var newReference = new ConversationReference()
        {
            Bot = new ChannelAccount()
            {
                Id = conversationReference.Bot.Id
            },
            Conversation = new ConversationAccount()
            {
                Id = conversationReference.Conversation.Id
            },
            ServiceUrl = conversationReference.ServiceUrl,
        };

Exemple de code

Le tableau suivant fournit un exemple de code simple qui intègre le flux de conversation de base dans une application Teams et comment créer un nouveau fil de conversation dans un canal dans Teams :

Exemple de nom Description .NET Node.js Python Manifeste
Informations de base des conversations Teams Cet exemple d’application montre comment utiliser différents événements de conversation de bot disponibles dans Bot Framework v4 pour l’étendue personnelle et teams. View View View View
Démarrer un nouveau thread dans un canal Cet exemple montre comment démarrer un thread dans un canal d’équipe spécifique à l’aide de Bot Framework v4. View View View View
Installation proactive de l’application et envoi de notifications proactives Cet exemple indique comment utiliser l’installation proactive de l’application pour les utilisateurs et envoyer des notifications proactives en appelant les API Microsoft Graph. View View N/A View
Messagerie proactive Il s’agit d’un exemple qui montre comment enregistrer les informations de référence de conversation de l’utilisateur pour envoyer un message de rappel proactif à l’aide de Bots. View View N/A

Exemple de code supplémentaire de messagerie proactive

Étape suivante

Formatez vos messages robots.

Voir aussi