Conversations par chat de canal et de groupe avec un robot Microsoft TeamsChannel and Group chat conversations with a Microsoft Teams bot

Important

Les exemples de code de cette section sont basés sur 4,6 et les versions ultérieures du kit de développement logiciel (SDK) de l’infrastructure bot.The code samples in this section are based on 4.6 and later versions of the Bot Framework SDK. Si vous recherchez de la documentation pour les versions antérieures, reportez-vous à la section SDK-v3 SDK dans le dossier Resources de la documentation.If you're looking for documentation for earlier versions, see the Bots - v3 SDK section in the Resources folder of the documentation.

En ajoutant l' teams groupchat étendue ou à votre robot, celle-ci peut être disponible pour être installée dans une conversation d’équipe ou de groupe.By adding the teams or groupchat scope to your bot, it can be available to be installed in a team or group chat. Cela permet à tous les membres de la conversation d’interagir avec votre robot.This allows all members of the conversation to interact with your bot. Une fois l’installation terminée, ils auront également accès aux métadonnées relatives à la conversation, telles que la liste des membres de la conversation. Si elle est installée dans une équipe, ils auront également accès aux détails de l’équipe et à la liste complète des canaux.Once installed, it will also have access to metadata about the conversation like the list of conversation members, and when installed in a team details about that team and the full list of channels.

Les robots d’un groupe ou d’un canal reçoivent uniquement les messages lorsqu’ils sont mentionnés (« @botname »), mais ils ne reçoivent pas les autres messages envoyés à la conversation.Bots in a group or channel only receive messages when they are mentioned ("@botname"), they do not receive any other messages sent to the conversation.

Notes

Le robot doit être @mentionné directement.The bot must be @mentioned directly. Votre bot ne reçoit pas de message lorsque l’équipe ou le canal est mentionné, ou lorsqu’un utilisateur répond à un message de votre robot sans le @mentioning.Your bot will not receive a message when the team or channel is mentioned, or when someone replies to a message from your bot without @mentioning it.

Considérations relatives à la conceptionDesign considerations

Un bot doit fournir des informations qui sont à la fois appropriées et pertinentes pour tous les membres d’un groupe ou d’un canal.A bot should provide information that is both appropriate and relevant to all members in a group or channel. Les conversations avec celles-ci sont visibles par tous les membres du groupe ou du canal.Conversations with it are visible to everyone that is a part of the group or channel. Un robot bien conçu peut ajouter de la valeur à tous les utilisateurs tout en ne partageant pas d’informations plus appropriées dans une conversation un-à-un.A well designed bot can add value to all users while not inadvertently sharing information that is more appropriate in a one-to-one conversation. Les conversations à plusieurs tours comme les boîtes de dialogue doivent être évitées-utilisez des cartes et/ou des modules de tâches pour collecter des informations à la place.Multi-turn conversations like dialogs should be avoided - use cards and/or task modules to collect information instead.

Création de threads de conversationCreating new conversation threads

Lorsque votre bot est installé dans une équipe, il est parfois nécessaire de créer un nouveau fil de conversation au lieu de répondre à un thread existant.When your bot is installed in a team, it can sometimes be necessary to create a new conversation thread rather than replying to an existing one. Il s’agit d’une forme de messagerie proactive.This is a form of proactive messaging.

Utilisation des mentionsWorking with mentions

Tous les messages à votre robot provenant d’un groupe ou d’un canal contiennent une @mention avec son propre nom dans le texte du message. Vous devez donc vous assurer que l’analyse de message gère cela.Every message to your bot from a group or channel will contain an @mention with its own name in the message text, so you'll need to ensure your message parsing handles that. Votre robot peut également récupérer d’autres utilisateurs mentionnés dans un message et ajouter des mentions à tous les messages qu’il envoie.Your bot can also retrieve other users mentioned in a message, and add mentions to any messages it sends.

Suppression des mentions du texte d’un messageStripping mentions from message text

Il se peut que vous deviez retirer les @mentions du texte du message reçu par votre robot.You may find it necessary to strip out the @mentions from the text of the message your bot receives.

Récupération des mentionsRetrieving mentions

Les mentions sont renvoyées dans l' entities objet dans la charge utile et contiennent l’ID unique de l’utilisateur et, dans la plupart des cas, le nom de l’utilisateur mentionné.Mentions are returned in the entities object in payload and contain both the unique ID of the user and, in most cases, the name of user mentioned. Le texte du message inclut également la mention telle que <at>@John Smith<at>.The text of the message will also include the mention like <at>@John Smith<at>. Toutefois, vous ne devez pas compter sur le texte du message pour récupérer des informations sur l’utilisateur ; Il est possible que la personne qui envoie le message le modifie.However, you should not rely on the text in the message to retrieve any information about the user; it is possible for the person sending the message to alter it. À la place, utilisez l' entities objet.Instead, use the entities object.

Vous pouvez récupérer toutes les mentions dans le message en appelant la GetMentions fonction dans le kit de développement logiciel (SDK) du générateur de robots, qui renvoie un tableau d' Mention objets.You can retrieve all mentions in the message by calling the GetMentions function in the Bot Builder SDK which returns an array of Mention objects.

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

Ajout de mentions à vos messagesAdding mentions to your messages

Votre robot peut mentionner d’autres utilisateurs dans les messages publiés dans des canaux.Your bot can mention other users in messages posted into channels. Pour ce faire, votre message doit effectuer les opérations suivantes :To do this, your message must do the following:

L' Mention objet possède deux propriétés que vous devrez définir :The Mention object has two properties that you will need to set:

  • Inclure @username dans le texte du messageInclude @username in the message text
  • Inclure l’objet « mention » à l’intérieur de la collection EntitiesInclude the mention object inside the entities collection

Le kit de développement logiciel (SDK) de l’infrastructure fournit des méthodes et des objets d’assistance pour faciliter la création de la mention.The Bot Framework SDK provides helper methods and objects to make constructing the mention easier.

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

Envoi d’un message lors de l’installationSending a message on installation

Lorsque votre bot est d’abord ajouté au groupe ou à l’équipe, il peut s’avérer utile d’envoyer un message le mettant en place.When your bot is first added to the group or team, it may be useful to send a message introducing it. Le message doit fournir une brève description des fonctionnalités du bot et comment les utiliser.The message should provide a brief description of the bot's features, and how to use them. Vous pouvez vous abonner à l' conversationUpdate événement, avec le teamMemberAdded eventType.You'll want to subscribe to the conversationUpdate event, with the teamMemberAdded eventType. Étant donné que l’événement est envoyé lorsqu’un nouveau membre d’équipe est ajouté, vous devez vérifier si le nouveau membre ajouté est le bot.Since the event is sent when any new team member is added, you need to check to determine if the new member added is the bot. Pour plus d’informations, consultez la rubrique envoi d’un message de bienvenue à un nouveau membre de l’équipe.See Sending a welcome message to a new team member for more details.

Vous pouvez également envoyer un message personnel à chaque membre de l’équipe lorsque le bot est ajouté.You might also want to send a personal message to each member of the team when the bot is added. Pour ce faire, vous pouvez obtenir la liste de l’équipe et envoyer un message direct à chaque utilisateur.To do this, you could get the team roster and send each user a direct message.

Il n’est pas recommandé d’envoyer un message dans les situations suivantes :It is not recommended to send a message in the following situations:

  • L’équipe est grande (évidemment subjective, mais par exemple, plus de 100 membres).The team is large (obviously subjective, but for example larger than 100 members). Votre robot peut être considéré comme « spammer » et la personne qui l’a ajouté peut recevoir des plaintes, sauf si vous communiquez clairement la proposition de valeur de votre robot à tous ceux qui voient le message de bienvenue.Your bot may be seen as 'spammy' and the person who added it may get complaints unless you clearly communicate your bot's value proposition to everyone who sees the welcome message.
  • Votre robot est d’abord mentionné dans un groupe ou un canal (et n’est pas d’abord ajouté à une équipe)Your bot is first mentioned in a group or channel (versus being first added to a team)
  • Un groupe ou un canal est renommé.A group or channel is renamed
  • Un membre de l’équipe est ajouté à un groupe ou à un canalA team member is added to a group or channel

En savoir plusLearn more

Votre bot a accès à des informations supplémentaires sur la conversation de groupe ou sur l’équipe dans laquelle il est installé.Your bot has access to additional information about the group chat or team it is installed in. Consultez la rubrique obtenir le contexte teams pour en savoir plus sur les API disponibles pour votre robot.See get teams context for additional APIs available for your bot.

Il existe également des événements supplémentaires auxquels votre bot peut s’abonner et auquel il répond.There are also additional events that your bot can subscribe and respond to. Pour en savoir plus, consultez la rubrique s’abonner aux événements de conversation .See subscribe to conversation events to learn how.

Exemples de robots teamsTeams bot samples

Pour obtenir des exemples entièrement fonctionnels illustrant certaines de ces fonctionnalités, consultez les exemples teams de l’infrastructure bot.For a fully working samples demonstrating some of this functionality, check out the Teams samples for Bot Framework

ExempleSample DescriptionDescription .NET Core.NET Core JavaScriptJavaScript PythonPython
Bot de conversation teamsTeams Conversation Bot Gestion des événements de messagerie et de conversationMessaging and conversation event handling ViewView ViewView ViewView
Authentification avec OAuthPromptAuthentication with OAuthPrompt Authentification et messagerie de base dans bot Framework v4Authentication and basic messaging in Bot Framework v4 ViewView ViewView ViewView
Chargement de fichiers teamsTeams File Upload Échange de fichiers avec un bot dans une conversation un-à-unExchanging files with a bot in a one-to-one conversation viewview viewview viewview