Conversas de chat de grupo e canal com um bot do Microsoft TeamsChannel and Group chat conversations with a Microsoft Teams bot

Importante

Os exemplos de código nesta seção são baseados em 4,6 e versões posteriores do SDK da estrutura de bot.The code samples in this section are based on 4.6 and later versions of the Bot Framework SDK. Se você estiver procurando por documentação para versões anteriores, consulte a seção do SDK bots-v3 na pasta recursos da documentação.If you're looking for documentation for earlier versions, see the Bots - v3 SDK section in the Resources folder of the documentation.

Ao adicionar o teams groupchat escopo ou ao bot, ele pode estar disponível para ser instalado em uma equipe ou em um chat de grupo.By adding the teams or groupchat scope to your bot, it can be available to be installed in a team or group chat. Isso permite que todos os membros da conversa interajam com o bot.This allows all members of the conversation to interact with your bot. Depois de instalado, ele também terá acesso aos metadados sobre a conversa como a lista de membros da conversa e, quando instalado em detalhes da equipe sobre essa equipe e a lista completa de canais.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.

Os bots em um grupo ou canal só recebem mensagens quando são mencionadas ("@botname"), elas não recebem nenhuma outra mensagem enviada à conversa.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.

Observação

O bot deve ser @mentioned diretamente.The bot must be @mentioned directly. O bot não receberá uma mensagem quando a equipe ou canal for mencionado ou quando alguém responder a uma mensagem do bot sem @mentioning-la.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.

Considerações de designDesign considerations

Um bot deve fornecer informações apropriadas e relevantes a todos os membros em um grupo ou canal.A bot should provide information that is both appropriate and relevant to all members in a group or channel. Conversas com ela são visíveis para todas as pessoas que fazem parte do grupo ou canal.Conversations with it are visible to everyone that is a part of the group or channel. Um bot bem projetado pode adicionar valor a todos os usuários enquanto não compartilha inadvertidamente as informações mais apropriadas em uma conversa de um-para-um.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. Conversas multiturnas como caixas de diálogo devem ser evitadas-use cartões e/ou módulos de tarefas para coletar informações.Multi-turn conversations like dialogs should be avoided - use cards and/or task modules to collect information instead.

Criando novos threads de conversaCreating new conversation threads

Quando o bot é instalado em uma equipe, às vezes, pode ser necessário criar um novo thread de conversa em vez de responder a um existente.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. Essa é uma forma de mensagens pró-ativas.This is a form of proactive messaging.

Trabalhando com mençãoWorking with mentions

Cada mensagem para o bot a partir de um grupo ou canal conterá um @mention com seu próprio nome no texto da mensagem, portanto, você precisará garantir que as alças de análise da mensagem.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. O bot também pode recuperar outros usuários mencionados em uma mensagem e adicionar menção a qualquer mensagem enviada.Your bot can also retrieve other users mentioned in a message, and add mentions to any messages it sends.

Como retirar menção do texto da mensagemStripping mentions from message text

Você pode achar necessário retirar o @mentions do texto da mensagem que seu bot recebe.You may find it necessary to strip out the @mentions from the text of the message your bot receives.

Como recuperar mençãoRetrieving mentions

As menção são retornadas no entities objeto no Payload e contêm a identificação exclusiva do usuário e, na maioria dos casos, o nome do usuário mencionado.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. O texto da mensagem também incluirá a menção, como <at>@John Smith<at> .The text of the message will also include the mention like <at>@John Smith<at>. No entanto, você não deve confiar no texto da mensagem para recuperar as informações sobre o usuário; é possível que a pessoa que está enviando a mensagem a altere.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. Em vez disso, use o entities objeto.Instead, use the entities object.

Você pode recuperar todas as menção na mensagem chamando a GetMentions função no SDK do bot Builder, que retorna uma matriz de Mention objetos.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.");
    }
}

Adicionando menção às suas mensagensAdding mentions to your messages

O bot pode mencionar outros usuários em mensagens postadas em canais.Your bot can mention other users in messages posted into channels. Para fazer isso, sua mensagem deve fazer o seguinte:To do this, your message must do the following:

O Mention objeto tem duas propriedades que você precisará definir:The Mention object has two properties that you will need to set:

  • Incluir @username no texto da mensagemInclude @username in the message text
  • Incluir o objeto menção dentro da coleção EntitiesInclude the mention object inside the entities collection

O SDK da estrutura de bot fornece métodos e objetos auxiliares para facilitar a criação da menção.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);
}

Enviando uma mensagem na instalaçãoSending a message on installation

Quando seu bot é adicionado ao grupo ou equipe, pode ser útil enviar uma mensagem introduzindo-a.When your bot is first added to the group or team, it may be useful to send a message introducing it. A mensagem deve fornecer uma breve descrição dos recursos do bot e como usá-los.The message should provide a brief description of the bot's features, and how to use them. Você desejará inscrever-se no conversationUpdate evento com o teamMemberAdded EventType.You'll want to subscribe to the conversationUpdate event, with the teamMemberAdded eventType. Como o evento é enviado quando um novo membro da equipe é adicionado, você precisa verificar se o novo membro adicionado é o 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. Consulte Enviar uma mensagem de boas-vindas para um novo membro da equipe para obter mais detalhes.See Sending a welcome message to a new team member for more details.

Você também pode querer enviar uma mensagem pessoal para cada membro da equipe quando o bot é adicionado.You might also want to send a personal message to each member of the team when the bot is added. Para fazer isso, você pode obter a lista de equipes e enviar uma mensagem direta a cada usuário.To do this, you could get the team roster and send each user a direct message.

Não é recomendável enviar uma mensagem nas seguintes situações:It is not recommended to send a message in the following situations:

  • A equipe é grande (obviamente subjetiva, mas por exemplo, mais de 100 membros).The team is large (obviously subjective, but for example larger than 100 members). Seu bot pode ser visto como ' spam ' e a pessoa que o adicionou pode receber reclamações, a menos que você comunique claramente a proposta de valor do bot para todos os usuários que veem a mensagem de boas-vindas.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.
  • Seu bot é mencionado pela primeira vez em um grupo ou canal (em vez de ser adicionado a uma equipe)Your bot is first mentioned in a group or channel (versus being first added to a team)
  • Um grupo ou canal é renomeadoA group or channel is renamed
  • Um membro da equipe é adicionado a um grupo ou canalA team member is added to a group or channel

Saiba maisLearn more

Seu bot tem acesso a informações adicionais sobre o bate-papo de grupo ou equipe em que ele está instalado.Your bot has access to additional information about the group chat or team it is installed in. Veja obter o contexto do Microsoft Teams para APIs adicionais disponíveis para o bot.See get teams context for additional APIs available for your bot.

Há também outros eventos que o seu bot pode assinar e responder.There are also additional events that your bot can subscribe and respond to. Consulte inscrever-se em eventos de conversa para saber como.See subscribe to conversation events to learn how.

Exemplos de bot de equipesTeams bot samples

Para obter um exemplo completo que demonstra algumas dessas funcionalidades, confira o Teams Samples for bot FrameworkFor a fully working samples demonstrating some of this functionality, check out the Teams samples for Bot Framework

AmostraSample DescriçãoDescription .NET Core.NET Core JavaScriptJavaScript PythonPython
Bot de conversa do teamsTeams Conversation Bot Tratamento de eventos de conversa e mensagens.Messaging and conversation event handling. ViewView ViewView ViewView
Autenticação com OAuthPromptAuthentication with OAuthPrompt Autenticação e mensagens básicas na estrutura de bot v4.Authentication and basic messaging in Bot Framework v4. ViewView ViewView ViewView
Carregamento de arquivos do teamsTeams File Upload Trocando arquivos com um bot em uma conversa de um-para-um.Exchanging files with a bot in a one-to-one conversation. ViewView ViewView ViewView
Módulo de tarefaTask Module Demonstrar como recuperar um módulo de tarefa e os valores de cartões nele, para uma extensão de mensagens.Demonstrating how to retrieve a Task Module and values from cards in it, for a Messaging Extension. ViewView ViewView ViewView
Iniciar novo thread em um canalStart new thread in a channel Demonstrar como criar um novo thread em um canal.Demonstrating how to create a new thread in a channel. ViewView ViewView ViewView