Поделиться через

События бесед в вашем боте Teams

Важно!

Примеры кода в этом разделе основаны на версии 4.6 и более поздних версиях пакета SDK Bot Framework. Если вы ищете документацию по более ранним версиям, см. раздел пакет SDK для ботов версии 3 в папке Устаревшие пакеты SDK документации.

При создании чат-ботов для Microsoft Teams можно работать с событиями беседы. Microsoft Teams отправляет вашему боту уведомления о событиях в тех областях, где этот бот активен. Эти события можно обрабатывать программно и выполнять с ними те или иные действия, например:

  • отправлять приветственное сообщение при добавлении бота в команду;
  • отправлять приветственное сообщение при добавлении пользователя в команду или его удалении;
  • отправлять уведомление при создании, переименовании или удалении канала;
  • отправлять уведомление, когда пользователь ставит сообщению бота отметку «Нравится».
  • Определите канал по умолчанию для бота из пользовательского ввода (выбора) во время установки.

В следующем видео показано, как бот беседы может улучшить взаимодействие с клиентами за счет плавного и интеллектуального взаимодействия:


События обновления беседы

События обновления беседы можно использовать для предоставления более качественных уведомлений и эффективных действий бота.

Важно!

  • Вы можете добавлять новые события в любое время, и бот начнет их получать.
  • Разрабатывая бот, учитывайте возможность получения непредвиденных событий.
  • Если вы используете пакет SDK Bot Framework, бот автоматически отвечает на любые события, которые вы решили не обрабатывать, отправкой 200 - OK.
  • Когда клиент Службы коммуникации Azure (ACS) присоединяется к собранию Teams или покидает его, события обновления диалога не активируются.

Бот получает событие conversationUpdate во всех перечисленных ниже случаях:

  • При добавлении бота в беседу.
  • При добавлении в беседу или удалении из нее других участников.
  • При изменении метаданных беседы.

Событие conversationUpdate отправляется боту, когда поступают сведения об обновлении членства в командах, куда он добавлен. Бот также получает обновление при первом добавлении в личную беседу.

В следующей таблице приведен список событий Teams обновления беседы с дополнительными сведениями:

Выполненное действие EventType Вызываемый метод Описание Область
Канал создан channelCreated OnTeamsChannelCreatedAsync Создается канал. Команда
Канал переименован channelRenamed OnTeamsChannelRenamedAsync Канал переименован. Команда
Канал удален ChannelDeleted OnTeamsChannelDeletedAsync Идет удаление канала. Команда
Канал восстановлен channelRestored OnTeamsChannelRestoredAsync Канал восстанавливается. Команда
Участники добавлены membersAdded OnTeamsMembersAddedAsync Участник добавляется. Все
Элементы удалены membersRemoved OnTeamsMembersRemovedAsync Элемент удаляется. Все
Команда переименована teamRenamed OnTeamsTeamRenamedAsync Идет переименование команды. Команда
Команда удалена TeamDeleted OnTeamsTeamDeletedAsync Идет удаление команды. Команда
Команда архивирована teamArchived OnTeamsTeamArchivedAsync Идет архивирование команды. Команда
Архивация команды отменена teamUnarchived OnTeamsTeamUnarchivedAsync Идет восстановление команды из архива. Команда
Команда восстановлена teamRestored OnTeamsTeamRestoredAsync Команда восстанавливается Команда

Канал создан

Событие channelCreated отправляется боту каждый раз, когда создается новый канал в команде, в которой установлен бот.

В следующем коде показан пример события, созданного каналом:

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

Канал переименован

Событие channelRenamed отправляется боту при каждом переименовании канала в команде, в которой установлен бот.

В следующем коде показан пример события переименования канала:

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

Канал удален

Событие channelDeleted отправляется боту каждый раз, когда канал удаляется в команде, где установлен бот.

В следующем коде показан пример события удаления канала:

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

Канал восстановлен

Событие channelRestored отправляется боту каждый раз, когда ранее удаленный канал восстанавливается в команде, где бот уже установлен.

В следующем коде показан пример события восстановления канала:

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

Участники добавлены

Добавленное событие участника отправляется боту в следующих сценариях:

  1. При установке самого бота и добавлении в беседу

    В контексте команды в качестве conversation.id действия задается id канал, выбранный пользователем во время установки приложения, или канал, в котором был установлен бот.

  2. При добавлении пользователя в беседу, в которой установлен бот

    Идентификаторы пользователей, полученные в полезных данных события, являются уникальными для бота и могут кэшироваться для использования в будущем, например для непосредственного обмена сообщениями с пользователем.

При отправке события из контекста команды для добавленного участника действия eventType задается teamMemberAdded значение . Чтобы определить, является ли добавленный новый элемент самим ботом или пользователем, проверка Activity объект объекта turnContext. Если список MembersAdded содержит объект , где id совпадает с полем idRecipient объекта, то добавленный элемент является ботом, в противном случае это пользователь. Бот имеет id формат 28:<MicrosoftAppId>.

Совет

Используйте событие,InstallationUpdate чтобы определить, когда бот добавляется или удаляется из беседы.

В следующем коде показан пример добавленного события участниками команды:

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

Элементы удалены

Событие удаления участника отправляется боту в следующих сценариях:

  1. Когда бот удаляется и удаляется из беседы.
  2. При удалении пользователя из беседы, в которой установлен бот.

При отправке события из контекста команды для eventType действия, удаленного участника, задается teamMemberRemoved значение . Чтобы определить, был ли только что удаленный участник самим ботом или пользователем, проверьте объект Activity из turnContext. Если список MembersRemoved содержит объект , где id совпадает с полем idRecipient объекта, то добавленный элемент является ботом, в противном случае это пользователь. Идентификатор бота форматируется как 28:<MicrosoftAppId>.

Примечание.

При окончательном удалении пользователя из клиента инициируется событие membersRemoved conversationUpdate.

В следующем коде показан пример удаленного события участников команды:

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

Команда переименована

Бот получает уведомление при переименовании команды. Он получает событие conversationUpdate с eventType.teamRenamed в объекте channelData.

В следующем коде показан пример события, переименованного командой:

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

Команда удалена

При удалении команды бот получает уведомление. Он получает событие conversationUpdate с eventType.teamDeleted в объекте channelData.

В следующем коде показан пример события, удаленного командой:

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

Команда восстановлена

Бот получает уведомление о восстановлении команды после удаления. Он получает событие conversationUpdate с eventType.teamrestored в объекте channelData.

В следующем коде показан пример события восстановления команды:

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

Команда архивирована

Бот получает уведомление о том, что команда установлена и архивирована. Он получает событие conversationUpdate с eventType.teamarchived в объекте channelData.

В следующем фрагменте программного кода показан пример события "команда архивирована".

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

Архивация команды отменена

Бот получает уведомление об установке команды и восстановлении ее из архива. Он получает событие conversationUpdate с eventType.teamUnarchived в объекте channelData.

В следующем коде показан пример неархивированного события команды:

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

Теперь, когда вы работали с событиями обновления беседы, вы можете понять события реакции сообщения, которые происходят для различных реакций на сообщение.

События реакции на сообщение

Событие messageReaction отправляется, когда пользователь добавляет или удаляет реакции на сообщение, отправленное ботом. replyToId содержит идентификатор сообщения, а Type - тип реакции в текстовом формате. В список типов реакций входят: гнев, любовь, смех, "нравится", печаль и удивление. Это событие не содержит содержимое исходного сообщения. Если обработка реакций на сообщения - важная функция бота, сохраняйте их при отправке. В следующей таблице приведены дополнительные сведения о типе события и объектах полезных данных:

EventType Объект полезных данных Описание Область
messageReaction reactionsAdded; Реакции, добавленные в сообщение бота. Все
messageReaction reactionsRemoved Реакции, удаленные из сообщения бота. Все

Реакции, добавленные в сообщение бота

В следующем фрагменте программного кода показан пример реакции на сообщение бота:

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

Реакции, удаленные из сообщения бота

В следующем фрагменте программного кода показан пример реакций, удаленных из сообщения бота:

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

Событие обновления установки

Бот получает событие installationUpdate при установке бота в поток беседы. Удаление бота из потока также генерирует это событие. При установке бота полю действие в событии присваивается значение add, а при удалении полю действие присваивается значение remove.

Примечание.

При обновлении приложения бот получает installationUpdate событие только для добавления или удаления бота из манифеста. Во всех остальных случаях installationUpdate событие не активируется. При добавлении бота полю действие в событии присваивается значение add-upgrade, а при удалении - значение remove-upgrade.

Событие установки обновления

Используйте событие installationUpdate для отправки вводного сообщения от бота при установке. Это событие помогает обеспечить соответствие требованиям к конфиденциальности и хранению данных. При удалении бота можно также очистить и удалить данные пользователя или потока.

Аналогично событию conversationUpdate , которое отправляется при добавлении бота в команду, в качестве conversation.id installationUpdate события устанавливается идентификатор канала, выбранного пользователем во время установки приложения или канала, в котором произошла установка. Идентификатор представляет канал, в котором пользователь намерен работать с ботом, и должен использоваться ботом при отправке приветственного сообщения. В случаях, когда идентификатор канала "Общий" явно требуется, его можно получить в team.idchannelData.

В этом примере conversation.idconversationUpdate для действий и installationUpdate задается идентификатор канала ответа в команде Daves Demo.

Создание выбранного канала

Примечание.

Выбранный идентификатор канала устанавливается только для installationUpdateсобытий добавления , которые отправляются при установке приложения в команду.

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

Можно также использовать выделенный обработчик добавления или удаления сценариев в качестве альтернативного метода для записи события.

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

Поведение при удалении для личного приложения с ботом

При удалении приложения бот также удаляется. Отправив сообщение вашему приложению, пользователь получает код ответа 403. Бот получает код 403 в качестве ответа на новые сообщения, опубликованные им самим. Поведение после удаления ботов в области личного чата теперь согласовано с поведением в аналогичной ситуации в областях Teams и группового чата. Вы не сможете отправлять или получать сообщения после удаления приложения.

Код ответа удаления

Обработка событий установки и удаления

При использовании событий установки и удаления в некоторых случаях боты выдают исключения при получении непредвиденных событий из Teams, что происходит в следующих случаях:

  • Вы создаете бот без Microsoft Bot Framework SDK, и в результате бот выдает исключение при получении непредвиденного события.
  • Вы создаете бот с помощью Microsoft Bot Framework SDK и решаете изменить обработку события по умолчанию путем переопределения базового дескриптора события.

Важно знать, что новые события могут быть добавлены в любое время в будущем, и ваш бот начнет получать их. Поэтому необходимо спроектировать возможность получения непредвиденных событий. Если вы используете пакет SDK Bot Framework, бот автоматически отвечает 200 –ОК на любые события, которые вы не решили обрабатывать.

Обработка ошибок в событиях диалога

Когда бот обнаруживает ошибку при обработке различных событий или действий, не отправляйте сообщения, не имеющие осмысленного контекста, в беседу, как показано на следующем снимке экрана:

Снимок экрана: сообщение об ошибке в беседе бота.

На этапе разработки всегда полезно отправлять содержательные сообщения в беседах, которые предоставляют дополнительные сведения о конкретной ошибке для лучшей отладки. Однако в рабочей среде необходимо регистрировать ошибки или события, чтобы приложение Azure Insights. Дополнительные сведения см. в статье Добавление данных телеметрии в бот.

Пример кода

Название примера Описание .NET Node.js Python Манифест
Бот беседы Это приложение демонстрирует события бесед бота, поддерживающие адаптивные карточки, уведомления о прочтении и события обновления сообщений. Он включает в себя поддержку иммерсивного чтения для специальных возможностей. Просмотр Просмотр Просмотр Просмотр

Следующий этап

Отправка упреждающих сообщений

См. также