Messagerie proactive pour les bots

Importante

Cet article est basé sur le Kit de développement logiciel (SDK) Bot Framework v3. Si vous recherchez la documentation actuelle version 4.6 ou ultérieure du Kit de développement logiciel (SDK), consultez la section Bots conversationnels .

Un message proactif est un message envoyé par un bot pour démarrer une conversation. Vous pouvez souhaiter que votre bot engage une conversation pour de nombreuses raisons, notamment :

• Messages de bienvenue pour les conversations personnelles de bot.
• Réponses aux sondages.
• Notifications d’événements externes.

L’envoi d’un message pour démarrer un nouveau thread de conversation est différent de l’envoi d’un message en réponse à une conversation existante. Lorsque votre bot démarre une nouvelle conversation, il n'y a pas de conversation préexistante dans laquelle publier le message. Pour envoyer un message proactif, vous devez :

1. Décidez de ce que vous allez dire
2. Obtenir l’ID unique et l’ID de locataire de l’utilisateur
3. Envoyer le message

Lorsque vous créez des messages proactifs, vous devez appeler MicrosoftAppCredentials.TrustServiceUrlet transmettre l’URL du service avant de créer le ConnectorClient utilisé pour envoyer le message. Si ce n’est pas le cas, une réponse 401: Unauthorized est reçue par votre application. Pour plus d’informations, consultez les exemples.

Meilleures pratiques en matière de messagerie proactive

L’envoi de messages proactifs est un moyen efficace de communiquer avec vos utilisateurs. Toutefois, du point de vue des utilisateurs, le message s’affiche de manière spontanée. S’il y a un message de bienvenue, c’est la première fois qu’ils interagissent 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 proactifs sont généralement classés en deux catégories : les messages de bienvenue ou les messages de notification.

Les messages de bienvenue

Lorsque vous utilisez la messagerie proactive pour envoyer un message d’accueil à un utilisateur, assurez-vous que, du point de vue de l’utilisateur, le message semble non traité. S’il y a un message de bienvenue, c’est la première fois qu’ils interagissent avec votre application. Les meilleurs messages de bienvenue sont les suivants :

• Pourquoi ils reçoivent ce message: il doit être clair pour l’utilisateur pourquoi il reçoit ce message. Si votre bot a été installé dans un canal et que vous avez envoyé un message de bienvenue à tous les utilisateurs, indiquez-leur dans quel canal il a été installé et éventuellement qui l’a installé.
• Que proposez-vous: que peuvent-ils faire avec votre application ? Quelle valeur pouvez-vous leur apporter ?
• Que doivent-ils faire ensuite: invitez-les à essayer une commande ou à interagir avec votre application d’une certaine manière.

Les messages de notification

Lorsque vous utilisez la messagerie proactive pour envoyer des notifications, vous devez vous assurer que vos utilisateurs disposent d’un chemin clair pour effectuer des actions courantes en fonction de votre notification et d’une compréhension claire de la raison pour laquelle la notification s’est produite. Les messages de notification corrects incluent généralement :

• Ce qui s’est passé: une indication claire de la cause de la notification.
• Ce qui est arrivé à : Il doit être clair quel élément/chose a été mis à jour pour provoquer la notification.
• Qui l'a fait : Qui a pris l'action qui a provoqué l'envoi de la notification ?
• ce qu’ils peuvent faire: facilitez la prise d’actions par vos utilisateurs en fonction de vos notifications.
• comment ils peuvent refuser: indiquez un chemin d’accès permettant aux utilisateurs de refuser des notifications supplémentaires.

Obtenir les informations utilisateur nécessaires

Les bots peuvent créer des conversations avec un utilisateur Microsoft Teams individuel en obtenant l’ID unique et l’ID de locataire de l’utilisateur . Vous pouvez obtenir ces valeurs à l’aide de l’une des méthodes suivantes :

• En récupérant la liste d’équipe à partir d’un canal, votre application est installée.
• En les mettant en cache lorsqu’un utilisateur interagit avec votre bot dans un canal.
• Lorsqu’un utilisateur est @mentioned dans une conversation de canal le bot fait partie de.
• En les mettant en cache lorsque vous recevoir l’événement conversationUpdate lorsque votre application est installée dans une étendue personnelle, ou que de nouveaux membres sont ajoutés à un canal ou à une conversation de groupe qui s’y ajoute.

Installer votre application de manière proactive en utilisant Graph

Remarque

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

Parfois, il peut être nécessaire d’envoyer des messages proactifs aux utilisateurs qui n’ont pas déjà installé ou interagi avec votre application. Par exemple, vous souhaitez utiliser le communicateur d’entreprise pour envoyer des messages à l’échelle de votre organisation. Pour ce scénario, vous pouvez utiliser l’API Graph pour installer de manière proactive votre application pour vos utilisateurs, puis mettre en cache les valeurs nécessaires à partir du conversationUpdate événement que votre application recevra lors de l’installation.

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

Pour plus d’informations, consultez Installer des applications pour les utilisateurs dans la documentation Graph. Il existe également un exemple dans .NET.

Exemples

Veillez à vous authentifier et à disposer d’un jeton du porteur avant de créer une conversation à l’aide de l’API REST.

POST {Service URL of your bot}/v3/conversations

{
  "bot": {
    "id": "c38eda0f-e780-49ae-86f0-afb644203cf8",
    "name": "The Bot"
  },
  "members": [
    {
      "id": "29:012d20j1cjo20211"
    }
  ],
  "channelData": {
    "tenant": {
      "id": "197231joe-1209j01821-012kdjoj"
    }
  }
}

Indiquez id comme ID d’application de bot et name comme nom de bot. Vous pouvez obtenir le membersid à partir de votre objet bots TurnContext tel que turnContext.Activity.From.Id. De même, id de locataire, à partir de votre objet bots TurnContext tel que turnContext.Activity.ChannelData.Tenant.Id.

Vous devez fournir l’identifiant utilisateur et l’identifiant du client. Si l’appel réussit, l’API retourne l’objet de réponse suivant.

{
    "id":"a:1qhNLqpUtmuI6U35gzjsJn7uRnCkW8NiZALHfN8AMxdbprS1uta2aT-jytfIlsZR3UZeg3TsIONNInBHsdjzj3PtfHuhkxxvS1jZZ61UAbw8fIdXcNSJyTJm7YvHFOgxo"

}

Cet ID est l’ID de conversation unique de la conversation personnelle. Stockez cette valeur et réutilisez-la pour les interactions futures avec l’utilisateur.

Utilisation de .NET

Cet exemple utilise le package NuGet Microsoft.Bot.Connector.Teams.

// Create or get existing chat conversation with user
var response = client.Conversations.CreateOrGetDirectConversation(activity.Recipient, activity.From, activity.GetTenantId());

// Construct the message to post to conversation
Activity newActivity = new Activity()
{
    Text = "Hello",
    Type = ActivityTypes.Message,
    Conversation = new ConversationAccount
    {
        Id = response.Id
    },
};

// Post the message to chat conversation with user
await client.Conversations.SendToConversationAsync(newActivity, response.Id);

Utilisation de Node.js

var address =
{
    channelId: 'msteams',
    user: { id: userId },
    channelData: {
        tenant: {
            id: tenantId
        }
    },
    bot:
    {
        id: appId,
        name: appName
    },
    serviceUrl: session.message.address.serviceUrl,
    useAuth: true
}

var msg = new builder.Message().address(address);
msg.text('Hello, this is a notification');
bot.send(msg);

Créer une conversation de canal

Le bot de votre équipe peut créer une chaîne de réponse dans un canal. Si vous utilisez le Kit de développement logiciel (SDK) Node.js Teams, utilisez startReplyChain(), qui vous donne une adresse complète avec l’ID d’activité et l’ID de conversation corrects. Si vous utilisez C#, consultez l’exemple suivant.

Vous pouvez également utiliser l’API REST et émettre une requête POST pour /conversations ressource.

Exemples de création d’une conversation de canal

C#

L’exemple .NET provient de cet exemple

using Microsoft.Bot.Builder.Dialogs;
using Microsoft.Bot.Connector;
using Microsoft.Bot.Connector.Teams.Models;
using Microsoft.Teams.TemplateBotCSharp.Properties;
using System;
using System.Threading.Tasks;

namespace Microsoft.Teams.TemplateBotCSharp.Dialogs
{
    [Serializable]
    public class ProactiveMsgTo1to1Dialog : IDialog<object>
    {
        public async Task StartAsync(IDialogContext context)
        {
            if (context == null)
            {
                throw new ArgumentNullException(nameof(context));
            }

            var channelData = context.Activity.GetChannelData<TeamsChannelData>();
            var message = Activity.CreateMessageActivity();
            message.Text = "Hello World";

            var conversationParameters = new ConversationParameters
            {
                  IsGroup = true,
                  ChannelData = new TeamsChannelData
                  {
                      Channel = new ChannelInfo(channelData.Channel.Id),
                  },
                  Activity = (Activity) message
            };

            MicrosoftAppCredentials.TrustServiceUrl(serviceUrl, DateTime.MaxValue);
            var connectorClient = new ConnectorClient(new Uri(activity.ServiceUrl));
            var response = await connectorClient.Conversations.CreateConversationAsync(conversationParameters);

            context.Done<object>(null);
        }
    }
}

Node.js

export async function startReplyChain(chatConnector: builder.ChatConnector, message: builder.Message, channelId: string): Promise<builder.IChatConnectorAddress> {
    let activity = message.toMessage();

    // Build request
    let options: request.Options = {
        method: "POST",
        // We use urlJoin to concatenate urls. url.resolve should not be used here,
        // since it resolves urls as hrefs are resolved, which could result in losing
        // the last fragment of the serviceUrl
        url: urlJoin((activity.address as any).serviceUrl, "/v3/conversations"),
        body: {
            isGroup: true,
            activity: activity,
            channelData: {
                teamsChannelId: channelId,
            },
        },
        json: true,
    };

    let response = await sendRequestWithAccessToken(chatConnector, options);
    if (response && response.hasOwnProperty("id")) {
        let address = createAddressFromResponse(activity.address, response) as any;
        if (address.user) {
            delete address.user;
        }
        if (address.correlationId) {
            delete address.correlationId;
        }
        return address;
    } else {
        throw new Error("Failed to start reply chain: no conversation ID returned.");
    }
}

HTTP

POST {Service URL of your bot}/v3/conversations

{
    "activity": {
        "type": "message",
        "text": "new conversation"
    },
    "bot": {
        "id": "{{botID}}",
        "name": "{{botName}}"
    },
    "channelData":{
      "teamsChannelId":"{{teamID}}",
      "teamsTeamId":"{{teamID}}",
      "channel":{"id":"{{teamID}}"},
      "team":{"id":"{{teamID}}"},
      "tenant":{"id": "{{tenantID}}"}
    },
    "isGroup": true,
    "tenantId": "{{tenantID}}"
}

Vous pouvez obtenir le à partir de l’objet {Service URL of your bot}TurnContext comme turnContext.Activity.ServiceURL paramètre .

Vous pouvez obtenir le à partir de l’objet channelDataTurnContext comme turnContext.Activity.TeamsChannelData paramètre .

Indiquez id comme ID d’application de bot et name comme nom de bot. De même, id de locataire, à partir de votre objet bots TurnContext tel que turnContext.Activity.ChannelData.Tenant.Id.

De même, vous pouvez fournir pour teamIDteamsChannelId, teamsTeamId, channel, team dans channelData la section , qui envoie le message au canal général de l’équipe.

Si l’appel réussit, l’API retourne avec l’objet de réponse suivant :

{
    "id": "{{conversationID}}",
    "activityId": "{{activityID}}"
}

Voir aussi

Exemples Bot Framework