Conversations de canal et de groupe avec un bot

  • 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.

Pour installer le bot Microsoft Teams dans une conversation d’équipe ou de groupe, ajoutez l’étendue teams ou groupchat à votre bot. Cela permet à tous les membres de la conversation d’interagir avec votre robot. Une fois le bot installé, il a accès aux métadonnées relatives à la conversation, telles que la liste des membres de la conversation. En outre, lorsqu’il est installé dans une équipe, le bot a accès à des détails sur cette équipe et à la liste complète des canaux.

Les bots d’un groupe ou d’un canal reçoivent uniquement des messages lorsqu’ils sont mentionnés @botname. Ils ne reçoivent aucun autre message envoyé à la conversation. Le bot doit être @mentioned directement. Votre bot ne reçoit pas de message lorsque l’équipe ou le canal est mentionné, ou quand quelqu’un répond à un message de votre bot sans @mentioning celui-ci.

Remarque

  • RSC pour tous les messages de conversation est disponible uniquement dans la préversion publique pour les développeurs.
  • À l’aide du consentement spécifique à la ressource (RSC), les bots peuvent recevoir tous les messages de canal dans les équipes dans laquelle ils sont installés sans être @mentioned. Pour plus d’informations, consultez recevoir tous les messages de canal avec RSC.
  • La publication d’un message ou d’une carte adaptative sur un canal privé n’est actuellement pas prise en charge.

Regardez la vidéo suivante pour en savoir plus sur les conversations de conversation de canal et de groupe avec un bot :


Instructions de conception

Contrairement aux conversations personnelles, dans les conversations de groupe et les canaux, votre bot doit fournir une présentation rapide. Vous devez suivre ces instructions de conception de bot et d’autres. Pour plus d’informations sur la conception de bots dans Teams, consultez comment concevoir des conversations de bot dans des canaux et des conversations.

À présent, vous pouvez créer des threads de conversation et gérer facilement différentes conversations dans les canaux.

Créer des threads de conversation

Lorsque votre bot est installé dans une équipe, vous devez créer un thread de conversation au lieu de répondre à un thread existant. Parfois, il est difficile de faire la distinction entre deux conversations. Si la conversation est threadée, il est plus facile d’organiser et de gérer différentes conversations dans les canaux. Il s’agit d’une forme de messagerie proactive.

Ensuite, vous pouvez récupérer des mentions à l’aide de l’objet entities et ajouter des mentions à vos messages à l’aide de l’objet Mention .

Utiliser des mentions

Chaque message envoyé à votre bot à partir d’un groupe ou d’un canal contient un @mention avec son nom dans le texte du message. Votre bot peut également récupérer d’autres utilisateurs mentionnés dans un message et ajouter des mentions à tous les messages qu’il envoie.

Vous devez également supprimer le @mentions du contenu du message reçu par votre bot.

Récupérer les mentions

Les mentions sont retournées dans l’objet entities dans la charge utile et contiennent à la fois l’ID unique de l’utilisateur et le nom de l’utilisateur mentionné. Le texte du message inclut également la mention, par exemple <at>@John Smith<at>. Toutefois, ne vous fiez pas au texte du message pour récupérer des informations sur l’utilisateur. Il est possible que la personne qui envoie le message le modifie. Par conséquent, utilisez l’objet entities.

Vous pouvez récupérer toutes les mentions dans le message en appelant la fonction GetMentions dans le SDK Bot Builder, qui retourne un tableau d’objets Mention .

Le code suivant montre un exemple de récupération des mentions :

protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
{
    // Resolves the mentions from the entities activity.
    Mention[] mentions = turnContext.Activity.GetMentions();
    if(mentions != null)
    {
        ChannelAccount firstMention = mentions[0].Mentioned;

        // Sends a message activity to the sender of the incoming activity.
        await turnContext.SendActivityAsync($"Hello {firstMention.Name}");
    }
    else
    {
        // Sends a message activity to the sender of the incoming activity.
        await turnContext.SendActivityAsync("Aw, no one was mentioned.");
    }
}

Ajouter des mentions à vos messages

Il existe deux types de mentions :

Mention de l’utilisateur

Votre bot peut mention d’autres utilisateurs dans des messages publiés dans des canaux.

L’objet Mention a deux propriétés que vous devez définir à l’aide des éléments suivants :

  • Incluez @username dans le texte du message.
  • Incluez l’objet mention dans la collection d’entités.

Le SDK Bot Framework fournit des méthodes d’assistance et des objets pour créer des mentions.

Le code suivant montre un exemple d’ajout de mentions à vos messages :

protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
{
    var mention = new Mention
    {
        Mentioned = turnContext.Activity.From,
        Text = $"<at>{XmlConvert.EncodeName(turnContext.Activity.From.Name)}</at>",
        Type = "mention",
    };

    // Returns a simple text message.
    var replyActivity = MessageFactory.Text($"Hello {mention.Text}.");
    replyActivity.Entities = new List<Entity> { mention };

    // Sends an activity to the sender of the incoming activity.
    await turnContext.SendActivityAsync(replyActivity, cancellationToken);
}

Vous pouvez maintenant envoyer un message d’introduction lorsque votre bot est installé ou ajouté pour la première fois à un groupe ou à une équipe.

Balise mention

Votre bot peut mention des balises dans des sms et des cartes adaptatives publiées dans des canaux. Lorsque le bot @mentions utilise la balise dans un canal, la balise est mise en surbrillance et les personnes associées à la balise sont averties. Lorsqu’un utilisateur pointe sur la balise, une fenêtre contextuelle s’affiche avec les détails de la balise.

Remarque

Les mentions de balise ne sont pas prises en charge dans les locataires Government Community Cloud (GCC), GCC-High et Department of Defense (DoD).

Mentionner des balises dans un sms

Dans l’objet mention.properties , ajoutez la propriété 'type': 'tag'. Si la propriété 'type': 'tag' n’est pas ajoutée, le bot traite le mention comme un mention utilisateur.

Exemple :

est type:tag ajouté en tant que dans Properties ChannelAccount.

Référence du Kit de développement logiciel (SDK)

​var mention = new ChannelAccount(tagId, "Test Tag"); 
​mention.Properties = JObject.Parse("{'type': 'tag'}"); 
​var mentionObj = new Mention 
​{ 
​    Mentioned = mention, 
​    Text = "<at>Test Tag</at>" 
​}; 

​var replyActivity = MessageFactory.Text("Hello " + mentionObj.Text); 
​replyActivity.Entities = new List<Microsoft.Bot.Schema.Entity> { mentionObj }; 
​await turnContext.SendActivityAsync(replyActivity, cancellationToken);
Mentionner des balises dans une carte adaptative

Dans le schéma de carte adaptative, sous l’objet mentioned , ajoutez la "type": "tag" propriété . Si la "type": "tag" propriété n’est pas ajoutée, le bot traite le mention comme un mention utilisateur.

Vous pouvez obtenir la liste des balises disponibles dans le canal à l’aide de l’API List teamworkTags .

Exemple :

​{ 
​    "type": "mention", 
    ​"text": "<at>Test Tag</at>", 
​    "mentioned": { 
            ​"id": "base64 encoded id" ,// tag graph 64 base ID
​            "name": "Test Tag", 
            ​"type": "tag" 
​    } 
​}
Paramètres de requête
Nom Description
type Type de mention. Le type pris en charge est tag.
id Identificateur unique de la balise. Pour plus d’informations, consultez teamworkTag.
Code d’erreur
Code d'état Code d’erreur Valeurs de message Demande de nouvelle tentative Action du développeur
400 Code : Bad Request La balise mentionnée avec l’ID {id string} n’existe pas dans l’équipe actuelle
L’étiquette ne peut être mentionnée que dans le canal
Balise mentionnée non valide, car aucune balise n’existe dans l’équipe		 Non Réévaluez la charge utile de la demande pour les erreurs. Consultez le message d’erreur retourné pour plus d’informations.
502 Code : Bad Gateway ID de groupe d’équipe non valide
ID de locataire mal formé pour la balise
L’ID de mention ne peut pas être résolu		 Non Réessayez manuellement.
Limitations

Toute demande peut être évaluée par rapport à plusieurs limites, en fonction de l’étendue, du type de fenêtre (court et long), du nombre d’étiquettes par message et d’autres facteurs. La première limite à atteindre déclenche le comportement de limitation.

Veillez à ne pas dépasser les limites de limitation pour éviter l’échec de la remise des messages. Par exemple, un bot ne peut envoyer que deux messages avec des étiquettes mention dans une fenêtre de cinq secondes et chaque message peut avoir jusqu’à 10 balises.

Le tableau suivant répertorie les limites de limitation pour les mentions de balise dans un bot :

Portée Type de fenêtre Nombre d’étiquettes par message Fenêtres de temps (s) Nombre maximal de messages par fenêtre de temps
Par bot et par thread Court 10 5 2
  Long 10 60 5
Tous les bots par thread Court 10 5 4
  Entier long 10 60 5
Limitations
  • Les mentions de balise sont prises en charge uniquement dans le flux de messages bot-à-client avec du texte et une carte adaptative.
  • Les mentions de balise ne sont pas prises en charge dans les canaux partagés et privés.
  • Les mentions de balise ne sont pas prises en charge dans les connecteurs.
  • Les mentions de balise ne prennent pas en charge le flux d’appel dans un bot.

Envoyer un message lors de l’installation

Lorsque votre bot est ajouté pour la première fois au groupe ou à l’équipe, un message d’introduction doit être envoyé. Le message doit fournir une brève description des fonctionnalités du bot et comment les utiliser. Vous devez vous abonner à l’événement conversationUpdate avec le teamMemberAdded eventType. L’événement est envoyé lorsqu’un nouveau membre d’équipe est ajouté. Vérifiez si le nouveau membre ajouté est le bot. Pour plus d’informations, consultez envoyer un message de bienvenue à un nouveau membre de l’équipe.

Vous pouvez envoyer un message personnel à chaque membre de l’équipe lorsque le bot est ajouté. Pour ce faire, récupérez la liste de l’équipe et envoyez un message direct à chaque utilisateur.

Remarque

Assurez-vous que le message envoyé par le bot est pertinent et ajoute de la valeur au message initial et ne courrier indésirable pas les utilisateurs.

N’envoyez pas de message dans les cas suivants :

  • Lorsque l’équipe est grande, par exemple, plus de 100 membres. Votre bot peut être considéré comme du courrier indésirable et la personne qui l’a ajouté peut recevoir des plaintes. Vous devez communiquer clairement la proposition de valeur de votre bot à toutes les personnes qui voient le message d’accueil.
  • Votre bot est mentionné pour la première fois dans un groupe ou un canal au lieu d’être ajouté en premier à une équipe.
  • Un groupe ou un canal est renommé.
  • Un membre d’équipe est ajouté à un groupe ou à un canal.

Exemples de bot Teams

Exemple de code

Pour obtenir des exemples complets illustrant la fonctionnalité, consultez les exemples Teams suivants pour Bot Framework :

Exemple de nom Description .NET Node.js Python Manifeste
Bot de conversation Teams Cet exemple 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
Authentification avec OAuthPrompt Cet exemple montre l’authentification et la messagerie de base dans Bot Framework v4. View View View View
Chargement de fichiers Teams Cet exemple montre comment utiliser des fichiers avec un bot dans une conversation un-à-un. View View View View
Boîte de dialogue (appelée module de tâche dans TeamsJS v1.x) Cet exemple montre comment utiliser une boîte de dialogue et les valeurs des cartes qu’il contient pour une extension de message. View View View View
Démarrer un nouveau thread dans un canal Cet exemple montre comment utiliser un nouveau thread dans un canal à l’aide d’un bot. View View View View
Localisation des applications Teams Cet exemple montre comment utiliser la localisation d’applications Teams à l’aide d’un bot et d’un onglet. View View N/A View

Guide pas à pas

Suivez le guide pas à pas pour créer un bot de conversation Teams.

Étape suivante

S’abonner à des événements de conversation

Voir aussi