Messagerie proactive pour les bots

Un message proactif est un message envoyé par un bot pour démarrer une conversation. Vous souhaiterez peut-être que votre bot démarre une conversation pour de nombreuses raisons, notamment :

• Messages de bienvenue pour les conversations de bot personnel.
• 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’existe aucune conversation préexistante sur 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 de l’utilisateur et l’ID du locataire
3. Envoyer le message

Lors de la création de 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, votre application reçoit une 401: Unauthorized réponse. Pour plus d’informations, consultez les exemples.

Meilleures pratiques pour une messagerie proactive

L’envoi de messages proactifs est un moyen efficace de communiquer avec vos utilisateurs. Toutefois, du point de vue de l’utilisateur, le message apparaît comme non sollicité. 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 les informations complètes à l’utilisateur pour comprendre l’objectif de ce message.

Les messages proactifs appartiennent généralement à l’une des deux catégories, les messages de bienvenue ou les notifications.

Messages de bienvenue

Lorsque vous utilisez la messagerie proactive pour envoyer un message de bienvenue à un utilisateur, assurez-vous que du point de vue de l’utilisateur, le message apparaît non sollicité. 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 incluent :

• Pourquoi ils reçoivent ce message : L’utilisateur doit savoir 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, faites-leur savoir 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 manière ou d’une autre.

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 prendre des mesures courantes en fonction de votre notification et qu’ils comprennent clairement pourquoi la notification s’est produite. Les bons messages de notification incluent généralement :

• Que s’est-il passé : une indication claire de ce qui s’est passé pour provoquer la notification.
• Ce qui est arrivé à : Il devrait être clair quel élément/chose a été mis à jour pour provoquer la notification.
• Qui l’a fait : qui a effectué l’action qui a provoqué l’envoi de la notification ?
• Ce qu’ils peuvent faire : permettez à vos utilisateurs d’effectuer facilement des actions en fonction de vos notifications.
• Comment ils peuvent refuser : fournissez un chemin permettant aux utilisateurs de refuser les notifications supplémentaires.

Obtenir les informations nécessaires à l’utilisateur

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 dont le bot fait partie.
• En les mettant en cache lorsque vous recevez 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.

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

Parfois, il peut être nécessaire d’envoyer un message proactif aux utilisateurs qui n’ont pas encore installé ou interagi avec votre application. Par exemple, vous souhaitez utiliser le communicateur d’entreprise pour envoyer des messages à l’ensemble 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 de l’événement que votre application recevra lors de l’installationconversationUpdate.

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

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

Exemples

Assurez-vous de vous authentifier et d’avoir un jeton de 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"
    }
  }
}

Fournissez id l’ID de votre application bot et name le nom de votre bot. Vous pouvez obtenir l’objet de vos botsTurnContext, membersid tel que turnContext.Activity.From.Id. De même, id de client, à partir de vos bots TurnContext objet tel que turnContext.Activity.ChannelData.Tenant.Id.

Vous devez fournir l’ID utilisateur et l’ID du locataire. Si l’appel réussit, l’API retourne avec 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 de futures interactions 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éation d’une conversation de canal

Votre bot ajouté par l’équipe peut publier dans un canal pour créer une chaîne de réponses. Si vous utilisez le SDK Node.js Teams, utilisez startReplyChain(), ce qui vous donne une adresse entièrement remplie avec l’ID d’activité et l’ID de conversation appropriés. Si vous utilisez C#, consultez l’exemple suivant.

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

Exemples de création d’une conversation de canal

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);
        }
    }
}

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.");
    }
}

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}}"
}

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

from microsoft_teams.apps import App
from microsoft_teams.api import MessageActivityInput
import asyncio

# Bot credentials
app_id = "YOUR_BOT_APP_ID"
app_password = "YOUR_BOT_APP_SECRET"

# Conversation details (obtained from bot installation event)
conversation_id = "19:channelId@thread.tacv2"

# Initialize the Teams app
app = App(
    storage={},
    client_id=app_id,
    client_secret=app_password
)

# Create the message activity
activity = MessageActivityInput(text="Hello from proactive message!")

# Send proactive message using Teams SDK
# The SDK handles authentication, activity construction, and API calls
result = await app.send(
    conversation_id=conversation_id,
    activity=activity
)

Voir aussi

Exemples Bot Framework.