Conversations de canal et de groupe avec un bot

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.

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 :

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

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

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

@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

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

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

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

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

Code d’erreur

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 :

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.

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 :

Guide pas à pas

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

Étape suivante

Voir aussi

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