Беседы в каналах и групповых чатах с ботом Microsoft Teams

Статья
04/04/2023

Важно!

Эта статья основана на пакете SDK Bot Framework версии 3. Если вы ищете текущую документацию по пакету SDK версии 4.6 или более поздней, см. раздел Боты для бесед.

Microsoft Teams позволяет пользователям вводить ботов в беседы в канале или групповом чате. При добавлении бота в команду или чат все участники беседы могут пользоваться функциями бота прямо в беседе. Вы также можете получить доступ к функциям, зависящим от Teams, в боте, например запрашивать сведения о команде и @mentioning пользователей.

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

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

Боты, добавленные в команду, становятся еще одним участником команды и могут быть @mentioned частью беседы. На самом деле, боты получают сообщения только в том случае, если они являются @mentioned, поэтому другие беседы на канале не отправляются боту.

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

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

Разработка бота для группвых бесед или каналов использует те же функции, что и при разработке бота для личных бесед. Дополнительные события и данные в полезных данных предоставляют Teams информацию о группах и каналах. Эти различия, а также основные различия в общих функциях описаны в следующих разделах.

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

Дополнительные сведения о ботах, создающих сообщения в каналах, см. в разделе Упреждающий обмен сообщениями для ботов и, в частности, Создание беседы канала.

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

Бот в группе или канале помимо обычной схемы сообщенийтакже получает следующие свойства:

channelDataСм. Данные каналов Teams. В групповом чате бот содержит следующие сведения, относящиеся к конкретному чату.
conversation.id Идентификатор цепочки ответов, состоящий из идентификатора канала и идентификатора первого сообщения в цепочке ответов.
Значение conversation.isGroup равно true для сообщений бота в каналах и групповых чатах.
Возможные значения conversation.conversationType: groupChat или channel.
entities Может содержать одно или несколько упоминаний. Дополнительные сведения см. в разделе Упоминания.

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

Чтобы ответить на существующее сообщение, вызовите ReplyToActivity в .NET или session.send в Node.js. Пакет SDK Bot Builder обрабатывает все сведения.

Если вы решили использовать REST API, можно также вызвать конечную точку /conversations/{conversationId}/activities/{activityId}.

В канале ответ на сообщение виден как ответ на инициированную цепочку ответов. conversation.id содержит идентификатор канала и идентификатор сообщения верхнего уровня. Хотя всеми деталями занимается Bot Framework, conversation.id можно кэшировать для будущих ответов на этот поток беседы по мере необходимости.

@Упоминания

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

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

Упоминания возвращаются в полезных данных объекта entities и содержат как уникальный ИД пользователя, так и, в большинстве случаев, имя упомянутого пользователя. Вы можете получить все упоминания в сообщении, вызвав функцию вGetMentions из пакета SDK Bot Builder для .NET, которая возвращает массив объектов Mentioned .

Пример кода .NET: проверка и упоминание @bot

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, которая позволяет удалить все упоминания, включая упоминания бота.

Node.js пример кода: проверка и упоминание @bot

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, которая позволяет удалить все упоминания, включая упоминания бота.

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

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

Включите <at>@username</at> в текст сообщения.
Включите объект mention в коллекцию сущностей.

Пример .NET

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

// 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.js

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

Пример: исходящее сообщение, в котором упомянут пользователь

{
    "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"
}

Доступ к области группового чата или канала

Бот может не только отправлять и получать сообщения в группах и командах. Например, он также может получить список участников, включая сведения об их профиле и список каналов. Дополнительные сведения см. в разделе Получение контекста для бота Microsoft Teams.

Дополнительные ресурсы

Примеры Bot Framework.

Беседы в каналах и групповых чатах с ботом Microsoft Teams

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

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

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

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

Рекомендация. Приветственные сообщения в Teams

@Упоминания

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

Пример кода .NET: проверка и упоминание @bot

Node.js пример кода: проверка и упоминание @bot

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

Пример .NET

Пример Node.js

Пример: исходящее сообщение, в котором упомянут пользователь

Доступ к области группового чата или канала

Дополнительные ресурсы

Обратная связь

Дополнительные ресурсы