Предоставление общего доступа к отзыву:
Мы хотели бы ваши отзывы о документации разработчика Microsoft Teams. Ответьте на наш короткий трехпрошенный опрос.Пройти опрос
Этот браузер больше не поддерживается.
Выполните обновление до Microsoft Edge, чтобы воспользоваться новейшими функциями, обновлениями для системы безопасности и технической поддержкой.
Примеры кода в этом разделе основаны на версии 4.6 и более поздних версиях пакета SDK Bot Framework. Если вы ищете документацию по более ранним версиям, см. раздел пакет SDK для ботов версии 3 в папке Устаревшие пакеты SDK документации.
Чтобы установить Microsoft Teams бота в чате группы или команды, добавьте боту область teams или groupchat. В результате все участники беседы взаимодействовать с вашим ботом. После установки бот получает доступ к метаданным беседы, например к списку участников. Кроме того, при установке в команде бот имеет доступ к подробным сведениям об этой команде и полному списку каналов.
Боты в группе или канале получают сообщения только при упоминании @botname. Они не получают других сообщений, отправляемых в беседу. Бот должен быть @mentioned непосредственно. Бот не получает сообщение, когда упоминается команда или канал или когда кто-то отвечает на сообщение от вашего бота без @mentioning него.
Используя согласие для конкретного ресурса (RSC), бот может получать все сообщения канала в командах, в которых он установлен, без использования @mentioned. Дополнительные сведения см. в статье Получение всех сообщений канала с помощью RSC.
Публикация сообщения или адаптивной карточки в частном канале не поддерживается.
См. следующее видео, чтобы узнать о беседах в канале и групповом чате с ботом:
Рекомендации по дизайну
В отличие от личных чатов, в групповых чатах и каналах бот после добавления должен кратко представиться. Обязательно следуйте этим и другим рекомендациям по проектированию ботов. Подробнее о разработке ботов в Teams см. в статье Проектирование бесед ботов в каналах и чатах.
Теперь вы можете создавать новые цепочки бесед и легко управлять различными беседами в каналах.
Создание цепочки беседы
При установке бота в команде необходимо создать новый поток беседы, а не отвечать на существующий. Иногда трудно различить два разговора. Если беседа является потоковой, проще организовать различные беседы в каналах и управлять ими. Это форма упреждающего обмена сообщениями.
Затем можно получить упоминания с помощью объекта entities и добавить упоминания в сообщения с помощью объекта Mention.
Работа с @упоминаниями
Каждое сообщение боту из группы или канала содержит @mention объект с именем в тексте сообщения. Бот также может получать имена других пользователей, упоминаемых в таких сообщениях, и добавлять упоминания во все отправляемые им сообщения. Боты в групповых чатах позволяют упоминать пользователей с помощью @mention; однако они не поддерживают @everyone упоминания.
Кроме того, необходимо удалить @mentions из содержимого сообщения, которое получает бот.
Получение упоминаний
Упоминания возвращаются в полезных данных объекта entities и содержат как уникальный ИД пользователя, так и имя упомянутого пользователя. Текст сообщения также содержит упоминание, например <at>@John Smith<at>. Однако не полагайтесь на текст в сообщении для получения каких-либо сведений о пользователе. Пользователь, отправляющий сообщение, может изменить его. Поэтому используйте объект entities.
Вы можете получить все упоминания в сообщении, вызвав функцию GetMentions в пакете SDK Bot Builder, которая возвращает массив объектов Mention.
В следующем фрагменте программного кода показан пример получения упоминаний:
protectedoverrideasync Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
{
// Resolves the mentions from the entities activity.
Mention[] mentions = turnContext.Activity.GetMentions();
if(mentions != null)
{
ChannelAccount firstMention = mentions[0].Mentioned;
// Sends a message activity to the sender of the incoming activity.await turnContext.SendActivityAsync($"Hello {firstMention.Name}");
}
else
{
// Sends a message activity to the sender of the incoming activity.await turnContext.SendActivityAsync("Aw, no one was mentioned.");
}
}
this.onMessage(async (turnContext, next) => {
// Resolves the mentions from the entities activity.const mentions = TurnContext.getMentions(turnContext.activity);
if (mentions){
const firstMention = mentions[0].mentioned;
// Sends a message activity to the sender of the incoming activity.await turnContext.sendActivity(`Hello ${firstMention.name}.`);
} else {
// Sends a message activity to the sender of the incoming activity.await turnContext.sendActivity(`Aw, no one was mentioned.`);
}
await next();
});
@staticmethod
// Resolves the mentions from the entities of this activity.
defget_mentions(activity: Activity) -> List[Mention]:
result: List[Mention] = []
if activity.entities isnotNone:
for entity in activity.entities:
if entity.type.lower() == "mention":
result.append(entity)
return result
protectedoverrideasync Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
{
var mention = new Mention
{
Mentioned = turnContext.Activity.From,
Text = $"<at>{XmlConvert.EncodeName(turnContext.Activity.From.Name)}</at>",
Type = "mention",
};
// Returns a simple text message.var replyActivity = MessageFactory.Text($"Hello {mention.Text}.");
replyActivity.Entities = new List<Entity> { mention };
// Sends an activity to the sender of the incoming activity.await turnContext.SendActivityAsync(replyActivity, cancellationToken);
}
TypeScript
this.onMessage(async (turnContext, next) => {
const mention = {
mentioned: turnContext.activity.from,
text: `<at>${ new TextEncoder().encode(turnContext.activity.from.name) }</at>`,
type: "mention",
} as Mention;
// Returns a simple text message.const replyActivity = MessageFactory.text(`Hello ${mention.text}`);
replyActivity.entities = [mention];
// Sends a message activity to the sender of the incoming activity.await turnContext.sendActivity(replyActivity);
// By calling next() you ensure that the next BotHandler is run.await next();
});
Поле text в объекте в массиве entities должно соответствовать части поля сообщения text. Если это не так, упоминание игнорируется.
asyncdef_mention_activity(self, turn_context: TurnContext):
mention = Mention(
mentioned=turn_context.activity.from_property,
text=f"<at>{turn_context.activity.from_property.name}</at>",
type="mention"
)
// Returns a simple text message.
reply_activity = MessageFactory.text(f"Hello {mention.text}")
# Sends a message activity to the sender of the incoming activity.
reply_activity.entities = [Mention().deserialize(mention.serialize())]
await turn_context.send_activity(reply_activity)
Теперь ваш бот может представиться при первой установке или добавлении в группу или команду.
Поддержка идентификатора объекта Microsoft Entra и имени участника-пользователя в пользовательском упоминание
Боты поддерживают идентификаторы пользователей упоминание, такие как идентификатор объекта Microsoft Entra и имя участника-пользователя (UPN) в дополнение к существующим идентификаторам. Входящие веб-перехватчики начинают поддерживать упоминание пользователей в адаптивной карточке с идентификатором объекта Microsoft Entra и имени участника-пользователя.
В следующем фрагменте кода показан пример упоминания пользователей с идентификатором объекта Entra и именем участника-пользователя в текстовом сообщении:
C#
var userId = "Adele@microsoft.com"; //User Principle Namevar mention = new ChannelAccount(userId, "Adele");
var mentionObj = new Mention
{
Mentioned = mention,
Text = $"<at>{mention.Name}</at>" ,
Type = "mention"
};
// Returns a simple text message.var replyActivity = MessageFactory.Text($"Hello {mentionObj.Text}.");replyActivity.Entities = new List<Entity> { mentionObj };// Sends an activity to the sender of the incoming activity.await turnContext.SendActivityAsync(replyActivity, cancellationToken);
В следующем фрагменте кода показан пример упоминания пользователей с идентификатором объекта Entra и именем участника-пользователя в адаптивной карточке:
JSON
{
"type": "mention",
"text": "<at>Adele</at>",
"mentioned": {
"id": "Adele@microsoft.com" ,// User Principle Name
"name": "Adele"
}
}
Упоминание тегов
Бот может упоминание теги в текстовых сообщениях и адаптивных карточках, размещенных в каналах. Когда бот @mentions использует тег в канале, он выделяется и пользователи, связанные с тегом, получают уведомление. При наведении указателя мыши на тег появляется всплывающее окно со сведениями о теге.
В объекте mention.properties добавьте свойство 'type': 'tag'. Если свойство 'type': 'tag' не добавлено, бот обрабатывает упоминание как упоминание пользователя.
Пример:
Добавляется type:tag как в Properties ChannelAccount.
В схеме адаптивной карточки в объекте mentioned добавьте "type": "tag" свойство .
"type": "tag" Если свойство не добавлено, бот обрабатывает упоминание как упоминание пользователя.
Список тегов, доступных в канале, можно получить с помощью API list teamworkTags .
Пример:
JSON
{
"type": "mention",
"text": "<at>Test Tag</at>",
"mentioned": {
"id": "base64 encoded id" ,// tag graph 64 base ID
"name": "Test Tag",
"type": "tag"
}
}
Параметры запроса
Имя
Описание
type
Тип упоминание. Поддерживаемый тип — tag.
id
Уникальный идентификатор тега. Дополнительные сведения см. в разделе TeamworkTag.
Код ошибки
Код состояния
Код ошибки
Значения сообщений
Повторный запрос
Действие разработчика
400
Код: Bad Request
Упомянутый тег с идентификатором {id string} не существует в текущей команде Тег можно упомянуть только в канале Недопустимый упомянутый тег, так как в команде не существует тега
Нет
Переоценка полезных данных запроса на наличие ошибок. Проверьте возвращенное сообщение об ошибке для получения дополнительных сведений.
502
Код: Bad Gateway
Недопустимый идентификатор группы команды Неправильный идентификатор клиента для тега Не удается разрешить идентификатор упоминания
Нет
Повторите попытку вручную.
Пределы регулирования
Любой запрос может оцениваться с учетом нескольких ограничений в зависимости от область, типа окна (короткого и длинного), количества тегов на сообщение и других факторов. Первое достигнутое ограничение запускает действие регулирования.
Убедитесь, что не превышение ограничений регулирования, чтобы избежать неудачной доставки сообщений. Например, бот может отправлять только два сообщения с тегами упоминание в пятисекундном окне, и каждое сообщение может содержать только до 10 тегов.
В следующей таблице перечислены ограничения регулирования для упоминаний тегов в боте:
Размах
Тип окна
Количество тегов на сообщение
Временные окна (с)
Максимальное число сообщений в период времени
На бота на поток
Короткий
10
5
2
Длинный
10
60
5
Все боты на поток
Короткий
10
5
4
Длинное целое
10
60
5
Ограничения
Упоминания тегов поддерживаются только в потоке сообщений от бота к клиенту с текстом и адаптивной карточкой.
Упоминания тегов не поддерживаются в общих и частных каналах.
Упоминания тегов не поддерживаются в соединителях.
Упоминания тегов не поддерживают поток вызова в боте.
Отправка сообщения при установке
При первом добавлении бота в группу или команду необходимо отправить начальное приветственное сообщение. Сообщение должно содержать краткое описание функций бота и способы их использования. Необходимо подписаться на событие conversationUpdate с помощью eventType teamMemberAdded. Событие отправляется при добавлении нового участника команды. Проверьте, является ли добавленный новый участник ботом. Подробнее см. в статье Отправка приветственного сообщения новому участнику команды.
Убедитесь, что сообщение, отправленное ботом, является релевантной и добавляет ценность первоначальному сообщению и не отправляет нежелательной почты пользователям.
Не отправляйте сообщение в следующих случаях:
Если команда большая, например, превышает 100 участников. Бот может быть сочтен распространителем спама, а пользователь, который добавил его, может получать жалобы. Необходимо четко сообщить о полезности бота всем, кто видит приветственное сообщение.
Бот упоминается в группе или канале раньше, чем добавлен в команду.
Группа или канал переименованы.
Участник команды добавляется в группу или канал.
Пример кода
Полные рабочие примеры, демонстрирующие эту функциональность, см. в следующих примерах Teams для Bot Framework:
Название примера
Описание
.NET
Node.js
Python
Манифест
Бот для беседы в Teams
В этом примере показано, как использовать различные события бесед бота, доступные в bot framework версии 4 для личных и командных область.
Источник этого содержимого можно найти на GitHub, где также можно создавать и просматривать проблемы и запросы на вытягивание. Дополнительные сведения см. в нашем руководстве для участников.
Отзыв о Platform Docs
Platform Docs — это проект с открытым исходным кодом. Выберите ссылку, чтобы оставить отзыв:
Продемонстрировать навыки для планирования, развертывания, настройки и управления Microsoft Teams, чтобы сосредоточиться на эффективной и эффективной совместной работе и взаимодействии в среде Microsoft 365.