Беседы в каналах и группах для общения с помощью робота Microsoft TeamsChannel and Group chat conversations with a Microsoft Teams bot

Важно!

Примеры кода, приведенные в этом разделе, основаны на 4,6 и более поздних версиях пакета SDK Bot.The code samples in this section are based on 4.6 and later versions of the Bot Framework SDK. Если вы ищете документацию по более ранним версиям, ознакомьтесь с разделом Боты – v3 SDK в папке resources этой документации.If you're looking for documentation for earlier versions, see the Bots - v3 SDK section in the Resources folder of the documentation.

Добавление teams groupchat области или области к интерфейсу робота может быть доступна для установки в команде или группе чата.By adding the teams or groupchat scope to your bot, it can be available to be installed in a team or group chat. Это позволяет всем участникам беседы взаимодействовать с роботом.This allows all members of the conversation to interact with your bot. После установки он также будет иметь доступ к метаданным беседы, как к списку участников беседы, а также при установке в группе сведений о команде и полном списке каналов.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.

Боты в группе или канале получать сообщения только при их упоминании ("@botname"), они не получают никаких других сообщений, отправляемых в беседу.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.

Примечание

Bot должен быть @mentioned напрямую.The bot must be @mentioned directly. Программа-робот не получает сообщение при упоминании команды или канала, а также когда кто-то отвечает на сообщение от пользователя Bot, не @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.

Особенности дизайнаDesign considerations

Bot должен предоставлять сведения, которые соответствуют всем участникам группы или канала.A bot should provide information that is both appropriate and relevant to all members in a group or channel. Беседы с ним видны всем, которые являются частью группы или канала.Conversations with it are visible to everyone that is a part of the group or channel. С помощью хорошо спроектированного почтового робота можно добавить значение ко всем пользователям, не создавая при этом непреднамеренное совместное использование информации в беседе "один к одному".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. Для сбора информации в беседах, таких как диалоговые окна, следует избегать использования карточек и/или модулей задач.Multi-turn conversations like dialogs should be avoided - use cards and/or task modules to collect information instead.

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

При установке ленты в команду иногда может потребоваться создать новый поток бесед, а не отвечать на него.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. Это форма упреждающего обмена сообщениями.This is a form of proactive messaging.

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

Каждое сообщение для ленты из группы или канала будет содержать @mention с собственным именем в тексте сообщения, поэтому необходимо убедиться, что маркеры синтаксического анализа сообщения.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. С помощью Bot можно также получить других пользователей, упомянутых в сообщении, и добавить упоминания в сообщения, которые он отправляет.Your bot can also retrieve other users mentioned in a message, and add mentions to any messages it sends.

Удаление упоминаний из текста сообщенияStripping mentions from message text

Может потребоваться изъять @mentions из текста сообщения, полученного от ленты.You may find it necessary to strip out the @mentions from the text of the message your bot receives.

Получение упоминанийRetrieving mentions

Упоминания возвращаются в entities объекте полезных данных и содержат как уникальный идентификатор пользователя, так и, в большинстве случаев, имя пользователя, указанное пользователем.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. Текст сообщения также будет содержать упоминание о том, как <at>@John Smith<at> .The text of the message will also include the mention like <at>@John Smith<at>. Тем не менее, не следует полагаться на текст в сообщении, чтобы получить сведения о пользователе; пользователь, отправивший сообщение, может изменить его.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. Вместо этого используйте entities объект.Instead, use the entities object.

Вы можете получить все упоминания в сообщении, вызвав GetMentions функцию в пакете SDK построителя ленты, которая возвращает массив Mention объектов.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.");
    }
}

Добавление упоминания к сообщениямAdding mentions to your messages

Ваш Bot может заупоминаниь других пользователей в сообщениях, размещенных в каналах.Your bot can mention other users in messages posted into channels. Для этого сообщение должно выполнить следующие действия:To do this, your message must do the following:

У Mention объекта есть два свойства, которые необходимо задать:The Mention object has two properties that you will need to set:

  • Включение @username в текст сообщенияInclude @username in the message text
  • Добавление объекта упоминаемого объекта в коллекцию сущностейInclude the mention object inside the entities collection

Пакет SDK для ленты предоставляет вспомогательные методы и объекты для упрощения создания упоминания.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);
}

Отправка сообщения при установкеSending a message on installation

При первом добавлении ленты в группу или группу может быть полезно отправить сообщение.When your bot is first added to the group or team, it may be useful to send a message introducing it. Сообщение должно содержать краткое описание функций и их использования.The message should provide a brief description of the bot's features, and how to use them. Вы хотите подписаться на conversationUpdate событие с помощью teamMemberAdded EventType.You'll want to subscribe to the conversationUpdate event, with the teamMemberAdded eventType. Так как событие отправляется при добавлении нового члена группы, необходимо проверить, добавлен ли новый член 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. Узнайте больше о том, как Отправить приветственное сообщение новому участнику группы .See Sending a welcome message to a new team member for more details.

Кроме того, вы можете отправить личное сообщение каждому участнику команды при добавлении ленты.You might also want to send a personal message to each member of the team when the bot is added. Для этого вы можете получить список участников команды и отправить ему прямое сообщение.To do this, you could get the team roster and send each user a direct message.

Не рекомендуется отправлять сообщения в следующих ситуациях:It is not recommended to send a message in the following situations:

  • Команда является большой (субъективно субъективна, но например, более 100 членов).The team is large (obviously subjective, but for example larger than 100 members). Ваш робот может отображаться как "нежелательный", а пользователь, который добавил его, может получать жалобу, если вы не хотите явно сообщить о значении для пользователя, который видит приветственное сообщение.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.
  • Первый из них упоминается в группе или канале (в отличие от первого добавления в группу).Your bot is first mentioned in a group or channel (versus being first added to a team)
  • Переименование группы или каналаA group or channel is renamed
  • Участник группы добавляется в группу или каналA team member is added to a group or channel

ПодробнееLearn more

У вас есть доступ к дополнительным сведениям о групповой беседе или группе, в которой он установлен.Your bot has access to additional information about the group chat or team it is installed in. Ознакомьтесь с контекстом Get Teams , чтобы получить дополнительные API, доступные для ленты.See get teams context for additional APIs available for your bot.

Кроме того, существуют дополнительные события, на которые может подписаться и реагировать ваш робот.There are also additional events that your bot can subscribe and respond to. Узнайте, как подписаться на события беседы .See subscribe to conversation events to learn how.

Примеры ленты TeamsTeams bot samples

Для полностью работающих примеров, демонстрирующих некоторые из этих функций, ознакомьтесь со статьями примеры для Teams для Bot FrameworkFor a fully working samples demonstrating some of this functionality, check out the Teams samples for Bot Framework

ПримерSample ОписаниеDescription .NET Core.NET Core JavaScriptJavaScript PythonPython
Bot для бесед в TeamsTeams Conversation Bot Обработка событий сообщений и бесед.Messaging and conversation event handling. ViewView ViewView ViewView
Проверка подлинности с помощью ОауспромптAuthentication with OAuthPrompt Проверка подлинности и обычная система обмена сообщениями в Bot Framework v4.Authentication and basic messaging in Bot Framework v4. ViewView ViewView ViewView
Отправка файлов TeamsTeams File Upload Обмен файлами с помощью Bot в беседе "один к одному".Exchanging files with a bot in a one-to-one conversation. ViewView ViewView ViewView
Модуль задачTask Module Демонстрация извлечения модуля задачи и значений из карточек в ней для расширения обмена сообщениями.Demonstrating how to retrieve a Task Module and values from cards in it, for a Messaging Extension. ViewView ViewView ViewView
Запуск нового потока в каналеStart new thread in a channel Демонстрация создания нового потока в канале.Demonstrating how to create a new thread in a channel. ViewView ViewView ViewView