Partilhar via


Eventos de conversa em seu bot do Teams

Importante

Os exemplos de código nesta secção baseiam-se na versão 4.6 e versões posteriores do SDK do Bot Framework. Se estiver à procura de documentação para versões anteriores, veja a secção bots – SDK v3 na pasta SDKs Legados da documentação.

Ao criar seus bots de conversa do Microsoft Teams, você poderá trabalhar com eventos de conversa. O Teams envia notificações ao bot de eventos de conversa que ocorrem em escopos onde o bot está ativo. Você poderá capturar esses eventos em seu código e executar as seguintes ações:

  • Dispare uma mensagem de boas-vindas quando seu bot for adicionado a uma equipe.
  • Dispare uma mensagem de boas-vindas quando um novo membro da equipe for adicionado ou removido.
  • Dispare uma notificação quando um canal for criado, renomeado ou excluído.
  • Dispare uma notificação quando uma mensagem de bot for curtida por um usuário.
  • Identifique o canal predefinido do bot a partir da entrada do utilizador (seleção) durante a instalação.

O vídeo seguinte demonstra como um bot de conversação pode melhorar o envolvimento do cliente através de interações inteligentes e suaves:


Eventos de atualização de conversa

Pode utilizar eventos de atualização de conversação para fornecer melhores notificações e ações de bot eficazes.

Importante

  • Você poderá adicionar novos eventos a qualquer momento e seu bot começará a recebê-los.
  • Você deve projetar seu bot para receber eventos inesperados.
  • Se estiver usando o SDK do Bot Framework, o bot responderá automaticamente com um 200 - OK a todos os eventos que você escolher não manipular.
  • Quando um cliente Serviços de Comunicação do Azure (ACS) entra ou sai da reunião do Teams, não são acionados eventos de atualização de conversação.

Um bot receberá um evento conversationUpdate em um dos seguintes casos:

  • Quando o bot é adicionado a uma conversação.
  • Outros membros são adicionados ou removidos de uma conversa.
  • Os metadados da conversa foram alterados.

O evento conversationUpdate é enviado ao seu bot quando ele recebe informações sobre atualizações de membros para as equipes onde foi adicionado. Ele também receberá uma atualização quando for adicionado pela primeira vez para conversas pessoais.

A tabela a seguir mostra uma lista de eventos de atualização de conversa do Teams com mais detalhes:

Ação realizada EventType Método chamado Descrição Escopo
Canal criado channelCreated OnTeamsChannelCreatedAsync Um canal é criado. Equipe
Canal renomeado channelRenamed OnTeamsChannelRenamedAsync Um canal é renomeado. Equipe
Canal excluído channelDeleted OnTeamsChannelDeletedAsync Um canal é excluído. Equipe
Canal restaurado channelRestored OnTeamsChannelRestoredAsync Um canal é restaurado. Equipe
Membros adicionados membersAdded OnTeamsMembersAddedAsync Um membro é adicionado. Tudo
Membros removidos membersRemoved OnTeamsMembersRemovedAsync Um membro é removido. Todos
Equipe renomeada teamRenamed OnTeamsTeamRenamedAsync Uma equipe é renomeada. Equipe
Equipe excluída teamDeleted OnTeamsTeamDeletedAsync Uma equipe é excluída. Equipe
Equipe arquivada teamArchived OnTeamsTeamArchivedAsync Uma equipe é arquivada. Equipe
Equipe desarquivada teamUnarchived OnTeamsTeamUnarchivedAsync Uma equipe é desarquivada. Equipe
Equipe restaurada teamRestored OnTeamsTeamRestoredAsync Uma equipe é restaurada Equipe

Canal criado

O channelCreated evento é enviado para o bot sempre que é criado um novo canal numa equipa onde o bot está instalado.

O código seguinte mostra um exemplo de um evento criado por canal:

protected override async Task OnTeamsChannelCreatedAsync(ChannelInfo channelInfo, TeamInfo teamInfo, ITurnContext<IConversationUpdateActivity> turnContext, CancellationToken cancellationToken)
{
    var heroCard = new HeroCard(text: $"{channelInfo.Name} is the Channel created");
    // Sends an activity to the sender of the incoming activity.
    await turnContext.SendActivityAsync(MessageFactory.Attachment(heroCard.ToAttachment()), cancellationToken);
}

Canal renomeado

O channelRenamed evento é enviado para o bot sempre que um canal é renomeado numa equipa onde o bot está instalado.

O código seguinte mostra um exemplo de um evento com o nome do canal mudado:

protected override async Task OnTeamsChannelRenamedAsync(ChannelInfo channelInfo, TeamInfo teamInfo, ITurnContext<IConversationUpdateActivity> turnContext, CancellationToken cancellationToken)
{
    var heroCard = new HeroCard(text: $"{channelInfo.Name} is the new Channel name");
    // Sends an activity to the sender of the incoming activity.
    await turnContext.SendActivityAsync(MessageFactory.Attachment(heroCard.ToAttachment()), cancellationToken);
}

Canal excluído

O channelDeleted evento é enviado para o bot sempre que um canal é eliminado numa equipa onde o bot está instalado.

O código seguinte mostra um exemplo de um evento eliminado do canal:

protected override async Task OnTeamsChannelDeletedAsync(ChannelInfo channelInfo, TeamInfo teamInfo, ITurnContext<IConversationUpdateActivity> turnContext, CancellationToken cancellationToken)
{
    var heroCard = new HeroCard(text: $"{channelInfo.Name} is the Channel deleted");
    await turnContext.SendActivityAsync(MessageFactory.Attachment(heroCard.ToAttachment()), cancellationToken);
}

Canal restaurado

O channelRestored evento é enviado para o bot sempre que um canal que foi eliminado anteriormente é restaurado numa equipa onde o bot já está instalado.

O código seguinte mostra um exemplo de um evento restaurado de canal:

protected override async Task OnTeamsChannelRestoredAsync(ChannelInfo channelInfo, TeamInfo teamInfo, ITurnContext<IConversationUpdateActivity> turnContext, CancellationToken cancellationToken)
{
    var heroCard = new HeroCard(text: $"{channelInfo.Name} is the Channel restored.");
    await turnContext.SendActivityAsync(MessageFactory.Attachment(heroCard.ToAttachment()), cancellationToken);
}

Membros adicionados

Um evento adicionado a um membro é enviado para o bot nos seguintes cenários:

  1. Quando o bot, por si só, é instalado e adicionado a uma conversação

    No contexto da equipa, o conversation.id da atividade é definido como o id do canal selecionado pelo utilizador durante a instalação da aplicação ou o canal onde o bot foi instalado.

  2. Quando um utilizador é adicionado a uma conversação onde o bot está instalado

    Os IDs de utilizador recebidos no payload do evento são exclusivos do bot e podem ser colocados em cache para utilização futura, como enviar mensagens diretas a um utilizador.

A atividade eventType adicionada pelo membro está definida como teamMemberAdded quando o evento é enviado a partir de um contexto de equipa. Para determinar se o novo membro adicionado foi o próprio bot ou um utilizador, marcar o Activity objeto do turnContext. Se a MembersAdded lista contiver um objeto em id que é o mesmo que o id campo do Recipient objeto, então o membro adicionado é o bot, caso contrário, é um utilizador. O bot está id formatado como 28:<MicrosoftAppId>.

Dica

Utilize o InstallationUpdate evento para determinar quando o bot é adicionado ou removido de uma conversação.

O código seguinte mostra um exemplo de um evento adicionado aos membros da equipa:

protected override async Task OnTeamsMembersAddedAsync(IList<TeamsChannelAccount> teamsMembersAdded , TeamInfo teamInfo, ITurnContext<IConversationUpdateActivity> turnContext, CancellationToken cancellationToken)
{
    foreach (TeamsChannelAccount member in teamsMembersAdded)
    {
        if (member.Id == turnContext.Activity.Recipient.Id)
        {
            // Send a message to introduce the bot to the team.
            var heroCard = new HeroCard(text: $"The {member.Name} bot has joined {teamInfo.Name}");
            // Sends an activity to the sender of the incoming activity.
            await turnContext.SendActivityAsync(MessageFactory.Attachment(heroCard.ToAttachment()), cancellationToken);
        }
        else
        {
            var heroCard = new HeroCard(text: $"{member.Name} joined {teamInfo.Name}");
            // Sends an activity to the sender of the incoming activity.
            await turnContext.SendActivityAsync(MessageFactory.Attachment(heroCard.ToAttachment()), cancellationToken);
        }
    }
}

Membros removidos

Um evento removido de membro é enviado para o bot nos seguintes cenários:

  1. Quando o bot, por si só, é desinstalado e removido de uma conversação.
  2. Quando um utilizador é removido de uma conversação onde o bot está instalado.

A atividade eventType removida do membro está definida como teamMemberRemoved quando o evento é enviado a partir de um contexto de equipa. Para determinar se o novo membro removido foi o próprio bot ou um usuário, verifique o objeto Activity do turnContext. Se a MembersRemoved lista contiver um objeto em id que é o mesmo que o id campo do Recipient objeto, então o membro adicionado é o bot, caso contrário, é um utilizador. O ID do bot está formatado como 28:<MicrosoftAppId>.

Observação

Quando um usuário for excluído permanentemente de um locatário, o evento membersRemoved conversationUpdate será disparado.

O código seguinte mostra um exemplo de um evento removido por membros da equipa:

protected override async Task OnTeamsMembersRemovedAsync(IList<ChannelAccount> membersRemoved, TeamInfo teamInfo, ITurnContext<IConversationUpdateActivity> turnContext, CancellationToken cancellationToken)
{
    foreach (TeamsChannelAccount member in membersRemoved)
    {
        if (member.Id == turnContext.Activity.Recipient.Id)
        {
            // The bot was removed.
            // You should clear any cached data you have for this team.
        }
        else
        {
            var heroCard = new HeroCard(text: $"{member.Name} was removed from {teamInfo.Name}");
            // Sends an activity to the sender of the incoming activity.
            await turnContext.SendActivityAsync(MessageFactory.Attachment(heroCard.ToAttachment()), cancellationToken);
        }
    }
}

Equipe renomeada

Seu bot será notificado quando a equipe for renomeada. Ele receberá um evento conversationUpdate com eventType.teamRenamed no objeto channelData.

O código seguinte mostra um exemplo de um evento cujo nome foi mudado pela equipa:

protected override async Task OnTeamsTeamRenamedAsync(TeamInfo teamInfo, ITurnContext<IConversationUpdateActivity> turnContext, CancellationToken cancellationToken)
{
    var heroCard = new HeroCard(text: $"{teamInfo.Name} is the new Team name");
    // Sends an activity to the sender of the incoming activity.
    await turnContext.SendActivityAsync(MessageFactory.Attachment(heroCard.ToAttachment()), cancellationToken);
}

Equipe excluída

O bot recebe uma notificação quando a equipa é eliminada. Ele receberá um evento conversationUpdate com eventType.teamDeleted no objeto channelData.

O código seguinte mostra um exemplo de um evento eliminado pela equipa:

protected override async Task OnTeamsTeamDeletedAsync(TeamInfo teamInfo, ITurnContext<IConversationUpdateActivity> turnContext, CancellationToken cancellationToken)
{
    // Handle delete event.
}

Equipe restaurada

O bot receberá uma notificação quando uma equipe for restaurada após ser excluída. Ele receberá um evento conversationUpdate com eventType.teamrestored no objeto channelData.

O código seguinte mostra um exemplo de um evento restaurado pela equipa:

protected override async Task OnTeamsTeamrestoredAsync(TeamInfo teamInfo, ITurnContext<IConversationUpdateActivity> turnContext, CancellationToken cancellationToken)
{
    var heroCard = new HeroCard(text: $"{teamInfo.Name} is the team name");
    // Sends an activity to the sender of the incoming activity.
    await turnContext.SendActivityAsync(MessageFactory.Attachment(heroCard.ToAttachment()), cancellationToken);
}

Equipe arquivada

O bot receberá uma notificação quando a equipe for instalada e arquivada. Ele receberá um evento conversationUpdate com eventType.teamarchived no objeto channelData.

O código a seguir mostra um exemplo do evento Equipe arquivada:

protected override async Task OnTeamsTeamArchivedAsync(TeamInfo teamInfo, ITurnContext<IConversationUpdateActivity> turnContext, CancellationToken cancellationToken)
{
    var heroCard = new HeroCard(text: $"{teamInfo.Name} is the team name");
     // Sends an activity to the sender of the incoming activity.
    await turnContext.SendActivityAsync(MessageFactory.Attachment(heroCard.ToAttachment()), cancellationToken);
}

Equipe desarquivada

O bot receberá uma notificação quando a equipe for instalada e desarquivada. Ele receberá um evento conversationUpdate com eventType.teamUnarchived no objeto channelData.

O código seguinte mostra um exemplo de um evento não arquivado da equipa:

protected override async Task OnTeamsTeamUnarchivedAsync(TeamInfo teamInfo, ITurnContext<IConversationUpdateActivity> turnContext, CancellationToken cancellationToken)
{
    var heroCard = new HeroCard(text: $"{teamInfo.Name} is the team name");
    // Sends an activity to the sender of the incoming activity.
    await turnContext.SendActivityAsync(MessageFactory.Attachment(heroCard.ToAttachment()), cancellationToken);
}

Agora que já trabalhou com os eventos de atualização de conversação, pode compreender os eventos de reação de mensagens que ocorrem para reações diferentes a uma mensagem.

Eventos de reação de mensagem

O messageReaction evento é enviado quando um utilizador adiciona ou remove reações a uma mensagem, que foi enviada pelo bot. O replyToId contém a ID da mensagem e o Type é o tipo de reação no formato de texto. Os tipos de reações incluem irritado, coração, gargalhada, curtir, triste e surpreso. Este evento não contém o conteúdo da mensagem original. Se o processamento de reações às suas mensagens for importante para o bot, você deverá armazenar as mensagens ao enviá-las. A tabela a seguir fornece mais informações sobre o tipo de evento e os objetos do conteúdo:

EventType Objeto do conteúdo Descrição Escopo
messageReaction reactionsAdded Reações adicionadas à mensagem do bot. Tudo
messageReaction reactionsRemoved Reações removidas da mensagem do bot. Tudo

Reações adicionadas à mensagem do bot

O código a seguir mostra um exemplo de reações a uma mensagem do bot:

protected override async Task OnReactionsAddedAsync(IList<MessageReaction> messageReactions, ITurnContext<IMessageReactionActivity> turnContext, CancellationToken cancellationToken)
{
    foreach (var reaction in messageReactions)
    {
      var newReaction = $"You reacted with '{reaction.Type}' to the following message: '{turnContext.Activity.ReplyToId}'";
      var replyActivity = MessageFactory.Text(newReaction);
      // Sends an activity to the sender of the incoming activity.
      var resourceResponse = await turnContext.SendActivityAsync(replyActivity, cancellationToken);
    }
}

Reações removidas da mensagem do bot

O código a seguir mostra um exemplo de reações removidas da mensagem do bot:

protected override async Task OnReactionsRemovedAsync(IList<MessageReaction> messageReactions, ITurnContext<IMessageReactionActivity> turnContext, CancellationToken cancellationToken)
{
    foreach (var reaction in messageReactions)
    {
      var newReaction = $"You removed the reaction '{reaction.Type}' from the following message: '{turnContext.Activity.ReplyToId}'";

      var replyActivity = MessageFactory.Text(newReaction);
      // Sends an activity to the sender of the incoming activity.
      var resourceResponse = await turnContext.SendActivityAsync(replyActivity, cancellationToken);
    }
}

Evento de atualização de instalação

O bot receberá um evento installationUpdate quando você instalar um bot em uma thread da conversa. A desinstalação do bot da thread também disparará o evento. Ao instalar um bot, o campo ação no evento será definido como adicionar, e quando o bot for desinstalado, o campo ação será definido como remover.

Observação

Quando atualiza uma aplicação, o bot recebe o installationUpdate evento apenas para adicionar ou remover um bot do manifesto. Para todos os outros casos, o installationUpdate evento não é acionado. O campo ação será definido como add-upgrade se você adicionar um bot ou remove-upgrade se você remover um bot.

Evento Instalar atualização

Use o evento installationUpdate para enviar uma mensagem introdutória do bot na instalação. Esse evento ajuda você a atender aos seus requisitos de privacidade e retenção. Você também poderá limpar e excluir dados de usuário ou thread quando o bot for desinstalado.

Semelhante ao evento que é enviado quando o conversationUpdate bot é adicionado a uma equipa, o conversation.id do installationUpdate evento é definido para o ID do canal selecionado por um utilizador durante a instalação da aplicação ou o canal onde ocorreu a instalação. O ID representa o canal onde o utilizador pretende que o bot funcione e tem de ser utilizado pelo bot ao enviar uma mensagem de boas-vindas. Para cenários em que o ID do canal Geral é explicitamente necessário, pode obtê-lo em team.idchannelData.

Neste exemplo, as conversation.idconversationUpdate atividades e installationUpdate estão definidas para o ID do canal Response na equipa de Demonstração da Daves.

Criar um canal selecionado

Observação

O ID de canal selecionado só é definido para installationUpdateadicionar eventos que são enviados quando uma aplicação é instalada numa equipa.

protected override async Task OnInstallationUpdateActivityAsync(ITurnContext<IInstallationUpdateActivity> turnContext, CancellationToken cancellationToken)
{
    var activity = turnContext.Activity;
    if (string.Equals(activity.Action, "Add", StringComparison.InvariantCultureIgnoreCase))
    {
        // TO:DO Installation workflow.
    }
    else
    {
        // TO:DO Uninstallation workflow.
    }
    return;
}

Você também poderá usar um manipulador dedicado para cenários adicionar ou remover como um método alternativo para capturar um evento.

protected override async Task OnInstallationUpdateAddAsync(ITurnContext<IInstallationUpdateActivity> turnContext, CancellationToken cancellationToken)
{
    // TO:DO Installation workflow return;
}

Comportamento de desinstalação do aplicativo pessoal com o bot

Quando você desinstalar um aplicativo, o bot também será desinstalado. Quando um usuário enviar uma mensagem para seu aplicativo, ele receberá um código de resposta 403. Seu bot receberá um código de resposta 403 para novas mensagens postadas pelo bot. O comportamento pós-desinstalação de bots no escopo pessoal com os escopos do Teams e do groupChat agora está alinhado. Não pode enviar ou receber mensagens depois de uma aplicação ter sido desinstalada.

Código de resposta de desinstalação

Manipulação de eventos para instalar e desinstalar eventos

Quando utiliza os eventos de instalação e desinstalação, existem algumas instâncias em que os bots dão exceções sobre a receção de eventos inesperados do Teams, o que ocorre nos seguintes casos:

  • Você projeta seu bot sem o SDK do Microsoft Bot Framework e, como resultado, o bot fornece uma exceção ao receber um evento inesperado.
  • Você projeta seu bot com o SDK do Microsoft Bot Framework e seleciona alterar o comportamento padrão do evento substituindo o identificador de evento base.

É importante saber que novos eventos podem ser adicionados em qualquer altura no futuro e o bot começa a recebê-los. Portanto, você deve projetar considerando a possibilidade de receber eventos inesperados. Se estiver a utilizar o SDK do Bot Framework, o bot responde automaticamente com um 200 – OK para quaisquer eventos que não opte por processar.

Lidar com erros em eventos de conversação

Quando um bot encontrar um erro ao processar diferentes eventos ou atividades, não envie mensagens que não tenham contexto significativo para a conversação, conforme mostrado na seguinte captura de ecrã:

Captura de ecrã a mostrar a resposta da mensagem de erro na conversação do bot.

Na fase de desenvolvimento, é sempre útil enviar mensagens relevantes em conversações, que fornecem detalhes adicionais sobre um erro específico para uma melhor depuração. No entanto, no ambiente de produção, tem de registar os erros ou eventos no Aplicativo Azure Insights. Para obter mais informações, consulte Adicionar telemetria ao bot.

Exemplo de código

Nome de exemplo Descrição .NET Node.js Python Manifesto
Bot de conversa Este exemplo mostra como utilizar diferentes eventos de conversação de bot disponíveis no Bot Framework v4 para o âmbito pessoal e de equipas. View View View View

Próxima etapa

Confira também