Conversations de canal et de groupe avec un bot

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), un bot peut recevoir tous les messages de canal dans les équipes dans laquelle il est installé 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 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. Les bots dans les conversations de groupe activent les mentions utilisateur à l’aide @mentionde ; toutefois, ils ne prennent pas en charge @everyone les mentions.

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 :

C#

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

• Exemple de référence de code

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

TypeScript

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

this.onMessage(async (turnContext, next) => {
    
    // Resolves the mentions from the entities activity.
    const mentions = TurnContext.getMentions(turnContext.activity);
    if (mentions){
        const firstMention = mentions[0].mentioned;

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

    await next();
});

JSON

{
    "type": "message",
    "text": "Hey <at>Pranav Smith</at> check out this message",
    "timestamp": "2017-10-29T00:51:05.9908157Z",
    "localTimestamp": "2017-10-28T17:51:05.9908157-07:00",
    "serviceUrl": "https://skype.botframework.com",
    "channelId": "msteams",
    "from": {
        "id": "29:9e52142b-5e5e-4d7b-bb3e-e82dcf620000",
        "name": "Jane Smith"
    },
    "conversation": {
        "id": "19:aebd0ad4d6ab42c8b9ed19c251c2fc37@thread.skype;messageid=1481567603816"
    },
    "recipient": {
        "id": "8:orgid:6aebbad0-e5a5-424a-834a-20fb051f3c1a",
        "name": "stlrgload100"
    },
    "attachments": [
        {
            "contentType": "image/png",
            "contentUrl": "https://upload.wikimedia.org/wikipedia/en/a/a6/Bender_Rodriguez.png",
            "name": "Bender_Rodriguez.png"
        }
    ],
    "entities": [
        {
            "type":"mention",
            "mentioned":{
                "id":"29:08q2j2o3jc09au90eucae",
                "name":"Pranav Smith"
            },
            "text": "<at>@Pranav Smith</at>"
        }
    ],
    "replyToId": "3UP4UTkzUk1zzeyW"
}

Python

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

@staticmethod
// Resolves the mentions from the entities of this activity.
def get_mentions(activity: Activity) -> List[Mention]:
    result: List[Mention] = []
    if activity.entities is not None:
        for entity in activity.entities:
            if entity.type.lower() == "mention":
                    result.append(entity)
     return result

Ajouter des mentions à vos messages

Il existe deux types de mentions :

• Mention de l’utilisateur
• Balise mention

Remarque

Les mention de mention et de balise utilisateur sont pris en charge pour les sms et les cartes adaptatives.

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 :

C#

• Référence du Kit de développement logiciel (SDK)
• Exemple de référence de code

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

TypeScript

this.onMessage(async (turnContext, next) => {
    const mention = {
        mentioned: turnContext.activity.from,
        text: `<at>${ new TextEncoder().encode(turnContext.activity.from.name) }</at>`,
        type: "mention",
    } as Mention;

    // Returns a simple text message.
    const replyActivity = MessageFactory.text(`Hello ${mention.text}`);
    replyActivity.entities = [mention];

    // Sends a message activity to the sender of the incoming activity.
    await turnContext.sendActivity(replyActivity);

    // By calling next() you ensure that the next BotHandler is run.
    await next();
});

JSON

Le champ text dans l’objet du tableau entities doit correspondre à une partie du champ text. Si ce n’est pas le cas, le mention est ignoré.

{
    "type": "message",
    "text": "Hey <at>Pranav Smith</at> check out this message",
    "timestamp": "2017-10-29T00:51:05.9908157Z",
    "localTimestamp": "2017-10-28T17:51:05.9908157-07:00",
    "serviceUrl": "https://skype.botframework.com",
    "channelId": "msteams",
    "from": {
        "id": "29:9e52142b-5e5e-4d7b-bb3e-e82dcf620000",
        "name": "Jane Smith"
    },
    "conversation": {
        "id": "19:aebd0ad4d6ab42c8b9ed19c251c2fc37@thread.skype;messageid=1481567603816"
    },
    "recipient": {
        "id": "8:orgid:6aebbad0-e5a5-424a-834a-20fb051f3c1a",
        "name": "stlrgload100"
    },
    "attachments": [
        {
            "contentType": "image/png",
            "contentUrl": "https://upload.wikimedia.org/wikipedia/en/a/a6/Bender_Rodriguez.png",
            "name": "Bender_Rodriguez.png"
        }
    ],
    "entities": [
        {
            "type":"mention",
            "mentioned":{
                "id":"29:08q2j2o3jc09au90eucae",
                "name":"Pranav Smith"
            },
            "text": "<at>@Pranav Smith</at>"
        }
    ],
    "replyToId": "3UP4UTkzUk1zzeyW"
}

Python

• Référence du Kit de développement logiciel (SDK)
• Exemple de référence de code

async def _mention_activity(self, turn_context: TurnContext):
        mention = Mention(
            mentioned=turn_context.activity.from_property,
            text=f"<at>{turn_context.activity.from_property.name}</at>",
            type="mention"
        )
        // Returns a simple text message.
        reply_activity = MessageFactory.text(f"Hello {mention.text}")
        # Sends a message activity to the sender of the incoming activity.
        reply_activity.entities = [Mention().deserialize(mention.serialize())]
        await turn_context.send_activity(reply_activity)

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.

Prise en charge de l’ID d’objet Microsoft Entra et de l’UPN dans les mention de l’utilisateur

Les bots prennent en charge les ID de mention utilisateur, tels que l’ID d’objet Microsoft Entra et le nom d’utilisateur principal (UPN) en plus des ID existants. Les webhooks entrants commencent à prendre en charge les mention utilisateur dans la carte adaptative avec l’ID d’objet Microsoft Entra et l’UPN.

L’extrait de code suivant montre un exemple de mention d’utilisateurs avec l’ID d’objet Entra et l’UPN dans un sms :

var userId = "Adele@microsoft.com"; //User Principle Name
var mention = new ChannelAccount(userId, "Adele"); 
var mentionObj = new Mention 
{
    Mentioned = mention,
    Text = $"<at>{mention.Name}</at>" ,
    Type = "mention"
}; 

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

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

L’extrait de code suivant montre un exemple de mention d’utilisateurs avec l’ID d’objet Entra et l’UPN dans une carte adaptative :

{
    "type": "mention",
    "text": "<at>Adele</at>",
    "mentioned": {
            "id": "Adele@microsoft.com" ,// User Principle Name
            "name": "Adele"
    }
} 

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.

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

• obtenir des de contexte Teams
• Créer un canal privé pour le compte de l’utilisateur
• Connecter un bot à Chat Web canal