Conversations de canal et de groupe avec un bot

Important

Les exemples de code de cette section sont basés sur la version 4.6 et les versions ultérieures du SDK Bot Framework. Si vous recherchez de la documentation pour les versions antérieures, consultez la section bots - V3 SDK dans le dossier Ressources de la documentation.

Pour installer le bot Microsoft Teams dans une conversation d’équipe ou de groupe, ajoutez l’étendue teams groupchat ou l’étendue à 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 sur 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 aux détails de 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 robot doit être @mentionné directement. Votre bot ne reçoit pas de message lorsque l’équipe ou le canal est mentionné, ou lorsqu’une personne répond à un message de votre bot sans @mentioning lui.

Notes

Cette fonctionnalité est actuellement disponible en prévisualisation pour les développeurs publics uniquement.

À l’aide du consentement spécifique aux ressources ( RSC), les bots peuvent recevoir tous les messages de canal dans les équipes dans qui il est installé sans être @mentioned. Pour plus d’informations, voir recevoir tous les messages de canal avec RSC.

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 et d’autres recommandations en matière de conception de bot. Pour plus d’informations sur la conception de bots dans Teams, voir comment concevoir des conversations de bot dans des canaux et des conversations.

À présent, vous pouvez créer de nouveaux 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 plutôt que de répondre à un thread existant. Parfois, il est difficile de différencier 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 et ajouter des entities mentions à vos messages à l’aide de Mention l’objet.

Travailler avec 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 les @mentions du contenu du message reçu par votre bot.

Récupérer des mentions

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

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

Le code suivant montre un exemple d’extraction de mentions :

protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
{
    Mention[] mentions = turnContext.Activity.GetMentions();
    if(mentions != null)
    {
        ChannelAccount firstMention = mentions[0].Mentioned;
        await turnContext.SendActivityAsync($"Hello {firstMention.Name}");
    }
    else
    {
        await turnContext.SendActivityAsync("Aw, no one was mentioned.");
    }
}

Ajouter des mentions à vos messages

Votre bot peut mentionner d’autres utilisateurs dans les messages publiés dans les canaux.

MentionL’objet possède deux propriétés que vous devez définir à l’aide des propriétés suivantes :

  • Incluez @username dans le texte du message.
  • Incluez l’objet mention à l’intérieur de la collection entities.

Le SDK Bot Framework fournit des méthodes d’aide 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>",
    };

    var replyActivity = MessageFactory.Text($"Hello {mention.Text}.");
    replyActivity.Entities = new List<Entity> { mention };

    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.

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 de leur utilisation. Vous devez vous abonner à conversationUpdate l’événement avec 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, voir l’envoi d’un message de bienvenue à un nouveau membre de l’équipe.

Envoyez un message personnel à chaque membre de l’équipe lorsque le bot est ajouté. Pour ce faire, obtenez la liste de l’équipe et envoyez un message direct à chaque utilisateur.

N’envoyez pas de message dans les cas suivants :

  • L’équipe est volumineuse, 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 obtenir des réclamations. Vous devez clairement communiquer la proposition de valeur de votre bot à toutes les personnes qui voient le message de bienvenue.
  • Votre bot est d’abord mentionné dans un groupe ou un canal au lieu d’être ajouté pour la première fois à une équipe.
  • Un groupe ou un canal est renommé.
  • Un membre d’équipe est ajouté à un groupe ou un canal.

Teams exemples de bot

Exemple de code

Pour obtenir des exemples de travail complets montrant les fonctionnalités, voir les exemples de Teams pour Bot Framework :

Échantillon Description .NET JavaScript Python
Bot de conversation Teams Gestion des événements de messagerie et de conversation. View View View
Authentification avec OAuthPrompt Authentification et messagerie de base dans Bot Framework v4. View View View
Teams téléchargement de fichier Échange de fichiers avec un bot dans une conversation un-à-un. View View View
Module de tâche Récupération d’un module de tâche et de valeurs à partir de cartes qu’il comprend pour une extension de messagerie. View View View
Démarrer un nouveau thread dans un canal Création d’un thread dans un canal. View View View

Étape suivante

Voir aussi

Obtenir Teams contexte