Messages proactifs

Important

Les exemples de code de cette section sont basés sur la version 4.6 et les versions ultérieures du SDK Bot Framework. Si vous recherchez de la documentation pour les versions antérieures, consultez la section bots - V3 SDK dans le dossier Ressources de la documentation.

Un message proactif est un message envoyé par un bot qui ne répond pas à une demande d’un utilisateur. Cela peut inclure des messages, tels que :

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

Pour que votre bot envoie un message proactif à un utilisateur, une conversation de groupe ou une équipe, il doit avoir accès pour envoyer le message. Pour une conversation de groupe ou une équipe, l’application qui contient votre bot doit d’abord être installée à cet emplacement. Vous pouvez installer votre application de manière proactive à l’aide de Microsoft Graph dans une équipe, si nécessaire, ou utiliser une stratégie d’application pour faire sortir les applications vers les équipes et les utilisateurs de votre client. Pour les utilisateurs, votre application doit être installée pour l’utilisateur ou votre utilisateur doit faire partie d’une équipe sur laquelle votre application est installée.

L’envoi d’un message proactif est différent de l’envoi d’un message normal. Il n’est pas actif turnContext à utiliser pour une réponse. Vous devez créer la conversation avant d’envoyer le message. Par exemple, une nouvelle conversation un-à-un ou un nouveau thread de conversation dans un canal. Vous ne pouvez pas créer une conversation de groupe ou un nouveau canal dans une équipe avec une messagerie proactive.

Pour envoyer un message proactif

  1. Obtenez l’ID d’utilisateur, l’ID d’équipe ou l’IDde canal, si nécessaire.
  2. Créez la conversation,si nécessaire.
  3. Obtenir l’ID de conversation.
  4. Envoyer le message.

Les extraits de code de la section exemples sont pour la création d’une conversation un-à-un. Pour obtenir des liens vers des exemples de travail complets pour les conversations un-à-un et les groupes ou canaux, voir l’exemple de code.

Pour utiliser efficacement les messages proactifs, consultez les meilleures pratiques en matière de messagerie proactive. Dans certains scénarios, vous devez installer votre application de manière proactive à l’aide Graph. Les extraits de code de la section exemples sont pour la création d’une conversation un-à-un. Pour obtenir des exemples de travail complets pour les conversations et les groupes ou canaux un-à-un, voir l’exemple de code.

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

Pour créer une conversation ou un thread de conversation dans un canal, vous devez avoir l’ID correct. Vous pouvez recevoir ou récupérer cet ID à l’aide des informations 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 onMembersAdded activité.
  • Vous pouvez récupérer la liste des canaux dans une équipe où votre application est installée.
  • Vous pouvez récupérer la liste des membres d’une équipe sur laquelle votre application est installée.
  • Chaque activité que reçoit votre bot doit contenir les informations requises.

Quelle que soit la façon dont vous obtenez les informations, vous devez stocker le ou pour tenantId userId créer une channelId conversation. Vous pouvez également l’utiliser pour créer un thread de conversation dans le canal général ou teamId par défaut d’une équipe.

Il userId est propre à votre ID de bot et à un utilisateur particulier. Vous ne pouvez pas réutiliser les userId bots. channelIdL’objectif est global. Toutefois, votre bot doit être installé dans l’équipe avant de pouvoir envoyer un message proactif à un canal.

Une fois que vous avez les informations de l’utilisateur ou du canal, vous devez créer la conversation.

Créer la conversation

Vous devez créer la conversation si elle n’existe pas ou si vous ne connaissez pas le conversationId . Vous ne devez créer la conversation qu’une seule fois et stocker la conversationId valeur ou conversationReference l’objet.

Une fois la conversation créée, vous devez obtenir l’ID de conversation.

Obtenir l’ID de conversation

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

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

Envoyer le message

Maintenant que vous avez les bonnes informations d’adresse, vous pouvez envoyer votre message. Si vous utilisez le SDK, vous devez utiliser la méthode, ainsi que la méthode et effectuer un continueConversation conversationId appel tenantId d’API direct. Vous devez définir correctement conversationParameters l’envoi de votre message. Consultez la section exemples ou utilisez l’un des exemples répertoriés dans la section exemple de code.

Maintenant que vous avez envoyé le message proactif, vous devez suivre ces meilleures pratiques tout en envoyant des messages proactifs pour un meilleur échange d’informations entre les utilisateurs et le bot.

Meilleures pratiques en matière de messagerie proactive

L’envoi de messages proactifs aux utilisateurs est un moyen efficace de communiquer avec vos utilisateurs. Toutefois, du point de vue de l’utilisateur, le message s’affiche de manière non improvisée. S’il existe un message de bienvenue, c’est la première fois qu’il interagit avec votre application. Il est important d’utiliser cette fonctionnalité et de fournir les 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 expliquer pourquoi les utilisateurs reçoivent le message. C’est également la première fois que les utilisateurs interagissent avec votre application. Il s’agit d’une opportunité de créer une bonne première impression. Les meilleurs messages de bienvenue doivent être les suivants :

  • Pourquoi un utilisateur reçoit le message : il doit être très clair pour l’utilisateur pourquoi il reçoit le message. Si votre bot 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é.
  • Que proposez-vous : les utilisateurs doivent être en mesure d’identifier ce qu’ils peuvent faire avec votre application et la valeur que vous pouvez leur apporter.
  • Que doivent-ils faire ensuite : inviter les utilisateurs à essayer une commande ou à interagir avec votre application. Les messages d’accueil médiocres peuvent amener les utilisateurs à bloquer votre bot. Écrivez au point et effacer les messages de bienvenue. Itérer sur les messages de bienvenue s’ils n’ont pas l’effet souhaité.

Les messages de notification

Pour envoyer des notifications à l’aide d’une messagerie proactive, assurez-vous que vos utilisateurs ont un chemin d’accès clair pour prendre des mesures communes en fonction de votre notification. Assurez-vous que les utilisateurs comprennent clairement pourquoi ils ont reçu une notification. Les messages de notification de bonne qualité sont généralement les suivants :

  • Ce qui s’est passé : une indication claire de ce qui est arrivé à l’origine de la notification.
  • Résultat : il doit être clair, quel élément est mis à jour pour obtenir la notification.
  • Qui ou ce qui l’a déclenché : Qui ou ce qui a pris des mesures, 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 aux utilisateurs pour qu’ils ne choisissent pas d’autres notifications.

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

Messages programmés

Lorsque vous utilisez une messagerie proactive pour envoyer des messages programmés aux utilisateurs, vérifiez que votre fuseau horaire est mis à jour vers leur fuseau horaire. Cela garantit que les messages sont remis aux utilisateurs au moment approprié. Les messages de planification incluent généralement :

  • Why is the user receiving the message: Make it easy for your users to understand the reason for which they’re receiving the message.
  • Que peut faire l’utilisateur ensuite : les utilisateurs peuvent prendre l’action requise en fonction du contenu du message.

Installer votre application de manière proactive à l’aide Graph

Notes

L’installation proactive des applications à l’Graph est actuellement en version bêta.

Envoyer un message de manière proactive 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’ensemble de votre organisation. Dans ce cas, vous pouvez utiliser l’API Graph pour installer de manière proactive votre application pour vos utilisateurs. Mettre en cache les valeurs nécessaires à partir conversationUpdate de l’événement que votre application reçoit lors de l’installation.

Vous pouvez uniquement installer des applications qui se trouver dans votre catalogue d’applications d’organisation ou dans Teams App Store.

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

Échantillons

Le code suivant montre 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)
        {
            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)
    {
        // If you encounter permission-related errors when sending this message, see
        // https://aka.ms/BotTrustServiceUrl
        await turnContext.SendActivityAsync("proactive hello");
    }
}

Notes

Actuellement, les bots ne peuvent pas créer de conversation de groupe par le biais d’API de bot ou de Graph. createConversation est disponible uniquement pour les conversations 1:1.

Exemple de code

Le tableau suivant fournit un exemple de code simple qui incorpore le flux de conversation de base dans une application Teams et comment créer un thread de conversation dans un canal dans Teams :

Exemple de nom Description .NET Node.js Python
Teams Informations de base sur les conversations Présente les principes de base des conversations Teams, notamment l’envoi de messages proactifs un-à-un. View View View
Démarrer un nouveau thread dans un canal Illustre la création d’un thread dans un canal. View View View
Installation proactive de l’application et envoi de notifications proactives Cet exemple montre comment utiliser l’installation proactive de l’application pour les utilisateurs et envoyer des notifications proactives en appelant les API Microsoft Graph. View View

Exemple de code supplémentaire

Étape suivante

Voir aussi