Телефонные и групповые беседы в чате с ботом

Важно!

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

Чтобы установить Microsoft Teams в командном или групповом чате, добавьте область или область teams groupchat в бот. В результате все участники беседы взаимодействовать с вашим ботом. После установки бота он имеет доступ к метаданным о беседе, например к списку участников беседы. Кроме того, при установке в команде бот имеет доступ к сведениям об этой группе и полном списке каналов.

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

Примечание

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

С помощью согласия на использование ресурсов (RSC) боты могут получать все сообщения каналов в командах, в которые он установлен без @mentioned. Дополнительные сведения см. в сообщении о приеме всех сообщений канала с помощью RSC.

Рекомендации по дизайну

В отличие от личных чатов, в групповых чатах и каналах бот должен предоставить быстрое введение. Необходимо следовать этим и дополнительным рекомендациям по разработке ботов. Дополнительные сведения о разработке ботов в Teams см. в том, как создать беседы ботов в каналах и чатах.

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

Создание новых потоков беседы

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

Далее можно получить упоминания с помощью объекта и добавить упоминания в entities сообщения с помощью Mention объекта.

Работа с упоминаниями

Каждое сообщение боту из группы или канала содержит @mention с его именем в тексте сообщения. Кроме того, бот может получать другие пользователи, упомянутые в сообщении, и добавлять упоминания в любые сообщения, которые он отправляет.

Кроме того, необходимо @mentions из содержимого сообщения, которое получает бот.

Извлечение упоминаний

Упоминания возвращаются в объекте в полезной нагрузке и содержат как уникальный ID пользователя, так и имя entities упомянутого пользователя. В тексте сообщения также содержится упоминание, например <at>@John Smith<at> . Однако не следует полагаться на текст в сообщении для получения сведений о пользователе. Это возможно для человека, отправляя сообщение, чтобы изменить его. Поэтому используйте entities объект.

Вы можете получить все упоминания в сообщении, позвонив функции в SDK Bot Builder, которая возвращает GetMentions массив Mention объектов.

В следующем коде показан пример упоминаний о том, как следующую возможность:

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

Добавление упоминаний в сообщения

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

Объект Mention имеет два свойства, которые необходимо установить, используя следующее:

  • *Включи @username* в текст сообщения.
  • Включай объект упоминания в коллекцию сущностями.

SDK Bot Framework предоставляет дополнительные методы и объекты для создания упоминаний.

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

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

Теперь вы можете отправить сообщение о вводе при первом установке или добавлении бота в группу или группу.

Отправка сообщения при установке

При первом добавлении бота в группу или группу необходимо отправить вводное сообщение. В сообщении должно быть краткое описание функций бота и их использования. Необходимо подписаться на conversationUpdate событие с teamMemberAdded помощью eventType. Событие отправляется при добавлении любого нового члена команды. Проверьте, является ли добавленный новый участник ботом. Дополнительные сведения см. в тексте отправки приветствия новому члену группы.

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

Не отправлять сообщение в следующих случаях:

  • Группа большая, например, более 100 участников. Ваш бот может рассматриваться как спам, а добавленный в него человек может получать жалобы. Необходимо четко донести предложение о ценности бота до всех, кто увидит приветствие.
  • Сначала бот упоминается в группе или канале, а не в команде.
  • Группа или канал переименованы.
  • Член группы добавляется в группу или канал.

Teams образцы ботов

Пример кода

Полные рабочие примеры, демонстрирующие функциональность, см. в следующих Teams для Bot Framework:

Пример Описание .NET JavaScript Python
Бот для беседы в Teams Обработка событий обмена сообщениями и бесед. View View View
Проверка подлинности с помощью OAuthPrompt Проверка подлинности и базовый обмен сообщениями в Bot Framework v4. View View View
Teams файла Обмен файлами с ботом в беседе один к одному. View View View
Модуль задач Ирисовка модуля задач и значений из карт в нем для расширения обмена сообщениями. View View View
Запуск нового потока в канале Создание нового потока в канале. View View View

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

См. также

Получить Teams контекст