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

Важно!

Статьи, приведенные в этом разделе, основаны на пакете SDK "V3 Bot Framework".The articles in this section are based on the v3 Bot Framework SDK. Если вы ищете текущую документацию (версия 4,6 или более поздняя версия пакета SDK), ознакомьтесь с разделом " беседы Боты ".If you're looking for current documentation (version 4.6 or later of the SDK) see the Conversational Bots section.

Microsoft Teams позволяет пользователям перенести боты в беседы по каналам или группового чата.Microsoft Teams allows users to bring bots into their channel or group chat conversations. Добавляя робота в группу или чат, все пользователи беседы могут воспользоваться всеми преимуществами функции Bot в беседе.By adding a bot to a team or chat, all users of the conversation can take advantage of the bot functionality right in the conversation. Вы также можете получать доступ к функциям, зависящим от Teams, в вашей почтовой среде, запрашивают сведения о команде и @mentioning пользователей.You can also access Teams-specific functionality within your bot like querying team information and @mentioning users.

Чат в каналах и беседах групп отличается от личного разговора тем, что пользователь должен @mention Bot.Chat in channels and group chats differ from personal chat in that the user needs to @mention the bot. Если используется в нескольких областях (личное, groupchat или Channel), необходимо определить область, из которой поступило сообщение Bot, и обработать их соответствующим образом.If a bot is used in multiple scopes (personal, groupchat or channel) you will need to detect what scope the bot messages came from, and process them accordingly.

Разработка отличного канала Bot для каналов или группDesigning a great bot for channels or groups

Боты, добавленный в команду, становится другим участником группы и может быть @mentioned в составе беседы.Bots added to a team become another team member and can be @mentioned as part of the conversation. На самом деле Боты получают сообщения только при @mentioned, поэтому другие беседы по каналу не отправляются в Bot.In fact, bots only receive messages when they are @mentioned, so other conversations on the channel are not sent to the bot.

В группе или канале Bot должна предоставляться информация, соответствующая всем участникам.A bot in a group or channel should provide information relevant and appropriate for all members. В то время как ваш Bot может предоставить любую информацию, относящуюся к опыту, следует учитывать, что беседы видны всем пользователям.While your bot can certainly provide any information relevant to the experience, keep in mind conversations with it are visible to everyone. Таким образом, для беседы с одним и тем же участником группы или канала должны быть добавлены все пользователи.Therefore, a great bot in a group or channel should add value to all users, and certainly not inadvertently share information more appropriate to a one-to-one conversation.

Ваш робот, как и то, может быть полностью связан со всеми областями без необходимости дополнительной работы.Your bot, just as it is, may be entirely relevant in all scopes without requiring additional work. В Microsoft Teams не предполагается, что функция Bot во всех областях, но вы должны убедиться, что у ленты есть пользовательское значение в любой области, которую вы выбрали для поддержки.In Microsoft Teams there is no expectation that your bot function in all scopes, but you should ensure that your bot provides user value in whichever scope(s) you choose to support. Для получения дополнительных сведений об областях обратитесь к разделу приложения в Microsoft Teams.For more information on scopes, see Apps in Microsoft Teams.

Разработка ленты, работающей в группах или каналах, использует те же функции, что и личные беседы.Developing a bot that works in groups or channels uses much of the same functionality as personal conversations. Дополнительные события и данные в полезных данных содержат сведения о группах и каналах Teams.Additional events and data in the payload provide Teams group and channel information. Эти отличия, а также ключевые отличия в общих функциональных возможностях описаны в следующих разделах.Those differences, as well as key differences in common functionality are described in the following sections.

Создание сообщенийCreating messages

Дополнительные сведения о Боты создании сообщений в каналах см в статье Active Messaging for Ботыи специальном создании беседы с каналом.For more information on bots creating messages in channels see Proactive messaging for bots, and specifically Creating a channel conversation.

Получение сообщенийReceiving messages

В дополнение к схеме обычных сообщенийдля Bot в группе или канале Bot также получают следующие свойства:For a bot in a group or channel, in addition to the regular message schema, your bot also receives the following properties:

  • channelData Ознакомьтесь с данными канала Teams.channelData See Teams channel data. В сеансе групповой беседы содержит сведения, относящиеся к этому разговору.In a group chat, contains information specific to that chat.
  • conversation.id ИДЕНТИФИКАТОР цепочки ответа, состоящий из идентификатора канала и идентификатора первого сообщения в цепочке ответа.conversation.id The reply chain ID, consisting of channel ID plus the ID of the first message in the reply chain
  • conversation.isGroup Предназначено true для сообщений Bot в каналах или групповых беседахconversation.isGroup Is true for bot messages in channels or group chats
  • conversation.conversationType Один groupChat или channelconversation.conversationType Either groupChat or channel
  • entities Может содержать одно или несколько упоминаний (см. упоминание)entities Can contain one or more mentions (see Mentions)

Ответ на сообщенияReplying to messages

Чтобы ответить на существующее сообщение, звоните ReplyToActivity в .NET или session.send в Node.js.To reply to an existing message, call ReplyToActivity in .NET or session.send in Node.js. Пакет SDK построителя построителя обрабатывает все подробные сведения.The Bot Builder SDK handles all the details.

Если вы решили использовать REST API, вы также можете вызвать /conversations/{conversationId}/activities/{activityId} конечную точку.If you choose to use the REST API, you can also call the /conversations/{conversationId}/activities/{activityId} endpoint.

В канале ответ на сообщение отображается как ответ на инициированную цепь ответа.In a channel, replying to a message shows as a reply to the initiating reply chain. conversation.idСодержит канал и идентификатор сообщения верхнего уровня.The conversation.id contains the channel and the top level message ID. Несмотря на то, что у Bot Framework есть сведения, вы можете кэшировать их conversation.id для будущих ответов на этот поток беседы по мере необходимости.Although the Bot Framework takes care of the details, you can cache that conversation.id for future replies to that conversation thread as needed.

Советы и рекомендации: приветственные сообщения в TeamsBest practice: Welcome messages in Teams

При первом добавлении ленты в группу или команду, как правило, полезно отправить приветственное сообщение для всех пользователей.When your bot is first added to the group or team, it is generally useful to send a welcome message introducing the bot to all users. Приветственное сообщение должно содержать описание функции и преимуществ пользователя Bot.The welcome message should provide a description of the bot’s functionality and user benefits. В идеале сообщение также должно включать команды для взаимодействия пользователя с приложением.Ideally the message should also include commands for the user to interact with the app. Для этого необходимо убедиться, что в объекте Bot реагирует на conversationUpdate сообщение с параметром teamsAddMembers EventType в channelData объекте.To do this, ensure that your bot responds to the conversationUpdate message, with the teamsAddMembers eventType in the channelData object. Убедитесь, что memberAdded идентификатор является собственно идентификатором приложения-робота, так как при добавлении пользователя в команду отправляется то же самое событие.Be sure that the memberAdded ID is the bot's App ID itself, because the same event is sent when a user is added to a team. Дополнительные сведения см. в разделе " участник группы" или "Добавление ленты ".See Team member or bot addition 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 fetch the team roster and send each user a direct message.

Не рекомендуется отправлять приветственное сообщение в следующих ситуациях:We recommend that your bot not send a welcome 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

@ Упоминания@ Mentions

Так как боты в группе или канале отвечают только на то, что они упоминаются ("@ботнаме") в сообщении, каждое сообщение, полученное в канале группы "bot", содержит собственное имя, и вы должны убедиться в том, что дескрипторы синтаксического анализа сообщений.Because bots in a group or channel respond only when they are mentioned ("@botname") in a message, every message received by a bot in a group channel contains its own name, and you must ensure your message parsing handles that. Кроме того, Боты может проанализировать других пользователей, упомянутых и упомянутых пользователям, в составе своих сообщений.In addition, bots can parse out other users mentioned and mention users as part of their messages.

Получение упоминаний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. Вы можете получить все упоминания в сообщении, вызвав GetMentions функцию в пакете SDK построителя построителя для .NET, которая возвращает массив Mentioned объектов.You can retrieve all mentions in the message by calling the GetMentions function in the Bot Builder SDK for .NET, which returns an array of Mentioned objects.

Пример кода .NET: Поиск и чередование @bot упоминаний.NET example code: Check for and strip @bot mention

Mention[] m = sourceMessage.GetMentions();
var messageText = sourceMessage.Text;

for (int i = 0;i < m.Length;i++)
{
    if (m[i].Mentioned.Id == sourceMessage.Recipient.Id)
    {
        //Bot is in the @mention list.
        //The below example will strip the bot name out of the message, so you can parse it as if it wasn't included. Note that the Text object will contain the full bot name, if applicable.
        if (m[i].Text != null)
            messageText = messageText.Replace(m[i].Text, "");
    }
}

Примечание

Вы также можете использовать функцию расширения Teams GetTextWithoutMentions , которая выполнит все упоминания, включая Bot.You can also use the Teams extension function GetTextWithoutMentions, which strips out all mentions, including the bot.

Node.js пример кода: Поиск и чередование @bot упоминанийNode.js example code: Check for and strip @bot mention

var text = message.text;
if (message.entities) {
    message.entities
        .filter(entity => ((entity.type === "mention") && (entity.mentioned.id.toLowerCase() === botId)))
        .forEach(entity => {
            text = text.replace(entity.text, "");
        });
    text = text.trim();
}

Вы также можете использовать функцию расширения Teams getTextWithoutMentions , которая выполнит все упоминания, включая Bot.You can also use the Teams extension function getTextWithoutMentions, which strips out all mentions, including the bot.

Создание упоминанийConstructing mentions

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

  • Включить <at>@username</at> в текст сообщенияInclude <at>@username</at> in the message text
  • Включение mention объекта в коллекцию сущностейInclude the mention object inside the entities collection

Пример .NET.NET example

В этом примере используется пакет NuGet Microsoft. Bot. Connector. Teams .This example uses the Microsoft.Bot.Connector.Teams NuGet package.

// Create reply activity
Activity replyActivity = activity.CreateReply();

// Construct text of the form @sender Hello
replyActivity.Text = "Hello ";
replyActivity.AddMentionToText(activity.From, MentionTextLocation.AppendText);

// Send the reply activity
await client.Conversations.ReplyToActivityAsync(replyActivity);

Пример Node.jsNode.js example

// User to mention
var toMention: builder.IIdentity = {
    name: 'John Doe',
    id: userId
};

// Create a message and add mention to it
var msg = new teams.TeamsMessage(session).text(teams.TeamsMessage.getTenantId(session.message));
var mentionedMsg = msg.addMentionToText(toMention);

// Post the message
var generalMessage = mentionedMsg.routeReplyToGeneralChannel();
session.send(generalMessage);

Пример: исходящее сообщение с указанным пользователемExample: Outgoing message with user mentioned

{
    "type": "message", 
    "text": "Hey <at>Pranav Smith</at> check out this message",
    "timestamp": "2017-10-29T00:51:05.9908157Z",
    "localTimestamp": "2017-10-28T17:51:05.9908157-07:00",
    "serviceUrl": "https://skype.botframework.com",
    "channelId": "msteams",
    "from": {
        "id": "28:9e52142b-5e5e-4d7b-bb3e- e82dcf620000",
        "name": "SchemaTestBot"
    },
    "conversation": {
        "id": "19:aebd0ad4d6ab42c8b9ed19c251c2fc37@thread.skype;messageid=1481567603816"
    },
    "recipient": {
        "id": "8:orgid:6aebbad0-e5a5-424a-834a-20fb051f3c1a",
        "name": "stlrgload100"
    },
    "attachments": [
        {
            "contentType": "image/png",
            "contentUrl": "https://upload.wikimedia.org/wikipedia/en/a/a6/Bender_Rodriguez.png",
            "name": "Bender_Rodriguez.png"
        }
    ],
    "entities": [
        {
            "type":"mention",
            "mentioned":{
                "id":"29:08q2j2o3jc09au90eucae",
                "name":"Pranav Smith"
            },
            "text": "<at>@Pranav Smith</at>"
        }
    ],
    "replyToId": "3UP4UTkzUk1zzeyW"
}

Доступ к области groupChat или каналаAccessing groupChat or channel scope

Ваш робот может выполнять больше, чем отправлять и получать сообщения в группах и в Teams.Your bot can do more than send and receive messages in groups and teams. Например, он также может получить список элементов, включая сведения о их профилях, а также список каналов.For instance, it can also fetch the list of members, including their profile information, as well as the list of channels. Чтобы узнать больше, ознакомьтесь со статьей получение контекста для робота Microsoft Teams .See Get context for your Microsoft Teams bot to learn more.

В этой статье также приведены примеры кода Bot Framework.See also Bot Framework samples.