Сообщения в беседах с ботами
Каждое сообщение в беседе Activity
является объектом типа messageType: message
. Когда пользователь отправляет сообщение, Microsoft Teams публикует действие сообщения боту. Teams отправляет объект JSON в конечную точку обмена сообщениями бота, а Teams разрешает только одну конечную точку для обмена сообщениями. Бот проверяет сообщение, чтобы определить его тип и ответить соответствующим образом.
Основные беседы обрабатываются через соединитель Bot Framework, один REST API. Этот API позволяет боту взаимодействовать с Teams и другими каналами. Пакет SDK Bot Builder предоставляет следующие возможности:
- Простой доступ к соединителю Bot Framework.
- Функциональные возможности для управления потоком и состоянием беседы.
- Простые способы внедрения когнитивных служб, такие как обработка естественного языка (NLP).
Бот получает сообщения из Teams с помощью Text
свойства и отправляет пользователям один или несколько ответов на сообщения.
Дополнительные сведения см. в разделе атрибуция пользователей для сообщений бота.
В следующей таблице перечислены действия, которые бот может получать и выполнять действия.
Тип | Объект полезных данных | Scope |
---|---|---|
Действие получения сообщения | Действие сообщения | Все |
Получение действия по изменению сообщения | Действие изменения сообщения | Все |
Действие получения отмены сообщения | Действие отмены сообщения | Все |
Действие получения сообщения обратимого удаления | Действие обратимого удаления сообщений | Все |
Действие получения сообщения
Чтобы получить текстовое Text
сообщение, используйте свойство Activity
объекта . В обработчике активности бота используйте объект контекста поворота Activity
для чтения одного запроса сообщения.
В следующем коде показан пример получения действия сообщения:
protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
{
// Sends an activity to the sender of the incoming activity.
await turnContext.SendActivityAsync(MessageFactory.Text($"Echo: {turnContext.Activity.Text}"), cancellationToken);
}
Получение уведомления о прочтении
Параметр Уведомления о прочтении в Teams позволяет отправителю сообщения чата получать уведомления о том, что его сообщение было прочитано получателем в чатах "один на один" и в групповых чатах. После того как получатель прочитает сообщение, рядом с ним появится значок Просмотрено . Вы также можете настроить бота для получения событий получения уведомлений о прочтении с помощью параметра Уведомления о прочтении . Событие уведомления о прочтении помогает улучшить взаимодействие с пользователем следующими способами:
Вы можете настроить бота для отправки последующего сообщения, если пользователь приложения не прочитал сообщение в личном чате.
Вы можете создать цикл обратной связи с помощью уведомлений о прочтении, чтобы настроить взаимодействие с ботом.
Примечание.
- Уведомления о прочтении поддерживаются только в сценариях чата между пользователями и ботами.
- Уведомления о прочтении ботов не поддерживают области группового, канала и группового чата.
- Если администратор клиента или пользователь отключает параметр Уведомления о прочтении , бот не получает событие уведомления о прочтении.
Чтобы получать события уведомлений о прочтении для бота, убедитесь в следующем:
- Добавьте разрешение RSC
ChatMessageReadReceipt.Read.Chat
в манифест приложения следующим образом:
- Манифест приложения версии 1.12 или более поздней версии
- Манифест приложения версии 1.11 или более ранней версии
"webApplicationInfo": {
"id": "38f0ca43-1c38-4c39-8097e-47f62c686500",
"resource": ""
},
"authorization": {
"permissions": {
"orgwide": [],
"resourceSpecific": [
{
"name": "ChatMessageReadReceipt.Read.Chat",
"type": "Application"
}
]
}
}
Вы также можете добавить разрешения RSC с помощью API Graph. Дополнительные сведения см. в статье consentedPermissionSet
.
Переопределите метод
OnTeamsReadReceiptAsync
обработчикомIsMessageRead
.Вспомогательный
IsMessageRead
метод полезен для определения того, считывается ли сообщение получателями.compareMessageId
Если значение меньше или равноLastReadMessageId
, сообщение было прочитано. ПереопределитеOnTeamsReadReceiptAsync
метод для получения уведомлений о прочтении с помощьюIsMessageRead
вспомогательного метода:protected override async Task OnTeamsReadReceiptAsync(ReadReceiptInfo readReceiptInfo, ITurnContext<IEventActivity> turnContext, CancellationToken cancellationToken) { var lastReadMessageId = readReceiptInfo.LastReadMessageId; if (IsMessageRead("{id of the message that you care}", LastReadMessageId)) { await turnContext.SendActivityAsync(MessageFactory.Text("User read the bot's message"), cancellationToken); } }
Ниже приведен пример запроса на событие получения уведомлений о прочтении, получаемого ботом:
{ "name": "application/vnd.microsoft.readReceipt", "type": "event", "timestamp": "2023-08-16T17:23:11.1366686Z", "id": "f:b4783e72-9d7b-2ed9-ccef-ab446c873007", "channelId": "msteams", "serviceUrl": "https://smba.trafficmanager.net/amer/", "from": { "id": "29:1-8Iuh70W9pRqV8tQK8o2nVjxz33RRGDKLf4Bh7gKnrzN8s7e4vCyrFwjkPbTCX_Co8c4aXwWvq3RBLr-WkkVMw", "aadObjectId": "5b649834-7412-4cce-9e69-176e95a394f5" }, "conversation": { "conversationType": "personal", "tenantId": "6babcaad-604b-40ac-a9d7-9fd97c0b779f", "id": "a:1xlimp68NSUxEqK0ap2rXuwC9ITauHgV2M4RaDPkeRhV8qMaFn-RyilMZ62YiVdqs8pp43yQaRKvv_U2S2gOS5nM-y_pOxVe4BW1qMGPtqD0Bv3pw-nJXF0zhDlZHMZ1Z" }, "recipient": { "id": "28:9901a8b6-4fef-428b-80b1-ddb59361adeb", "name": "Test Bot" }, "channelData": { "tenant": { "id": "6babcaad-604b-40ac-a9d7-9fd97c0b779f" } }, "value": { "lastReadMessageId": "1692206589131" } }
Параметр администратора квитанции на чтение или пользовательский параметр включен для клиента, чтобы бот получал события получения уведомлений о прочтении. Администратор клиента или пользователь должны включить или отключить параметр уведомления о прочтении.
После включения бота в сценарии чата пользователя бота бот быстро получает событие уведомления о прочтении, когда пользователь считывает сообщение бота. Вы можете отслеживать вовлеченность пользователей, подсчитывая количество событий, а также отправлять контекстное сообщение.
Отправка сообщения
Чтобы отправить текстовое сообщение, укажите строку, которую нужно отправить в качестве действия. В обработчике действий бота используйте метод объекта контекста поворота SendActivityAsync
для отправки одного ответа сообщения. Используйте метод объекта для отправки SendActivitiesAsync
нескольких ответов.
В следующем коде показан пример отправки сообщения при добавлении пользователя в беседу:
protected override async Task OnMembersAddedAsync(IList<ChannelAccount> membersAdded, ITurnContext<IConversationUpdateActivity> turnContext, CancellationToken cancellationToken)
{
// Sends an activity to the sender of the incoming activity.
await turnContext.SendActivityAsync(MessageFactory.Text($"Hello and welcome!"), cancellationToken);
}
Примечание.
- Разделение сообщений происходит, когда текстовое сообщение и вложение отправляются в одной и той же полезной нагрузке действия. Teams разделяет это действие на два отдельных действия: одно с текстовым сообщением, а другое с вложением. При разделении действия вы не получаете идентификатор сообщения в ответ, который используется для упреждающего обновления или удаления сообщения. Вместо разбиения сообщений рекомендуется отправлять отдельные действия.
- Отправленные сообщения можно локализовать для обеспечения персонализации. Дополнительные сведения см. в статье Локализация приложения.
Сообщения, отправляемые между пользователями и ботами, включают в себя данные внутреннего канала в сообщении. Эти данные позволяют боту правильно взаимодействовать по этому каналу. Пакет SDK Bot Builder позволяет изменять структуру сообщений.
Получение действия редактирования сообщения
При редактировании сообщения бот получает уведомление о действии изменения сообщения.
Чтобы получить уведомление об изменении сообщения в боте, можно переопределить OnTeamsMessageEditAsync
обработчик.
Ниже приведен пример уведомления об изменении сообщения с использованием OnTeamsMessageEditAsync
при редактировании отправленного сообщения:
protected override async Task OnTeamsMessageEditAsync(ITurnContext<IMessageUpdateActivity> turnContext, CancellationToken cancellationToken)
{
var replyActivity = MessageFactory.Text("message is updated");
await turnContext.SendActivityAsync(replyActivity, cancellationToken);
}
Получение действия отмены сообщения
При отмене удаления сообщения бот получает уведомление об активности отмены сообщения.
Чтобы получить уведомление о действиях отмены сообщения в боте, можно переопределить OnTeamsMessageUndeleteAsync
обработчик.
Ниже приведен пример уведомления об OnTeamsMessageUndeleteAsync
отмене сообщения при восстановлении удаленного сообщения.
protected override async Task OnTeamsMessageUndeleteAsync(ITurnContext<IMessageUpdateActivity> turnContext, CancellationToken cancellationToken)
{
var replyActivity = MessageFactory.Text("message is undeleted");
await turnContext.SendActivityAsync(replyActivity, cancellationToken);
}
Получение действия с обратимым удалением сообщений
При обратимом удалении сообщения бот получает уведомление об активности обратимого удаления сообщения.
Чтобы получить уведомление об активности сообщения обратимого удаления в боте, можно переопределить OnTeamsMessageSoftDeleteAsync
обработчик.
Ниже приведен пример уведомления об активности обратимого удаления сообщений при OnTeamsMessageSoftDeleteAsync
обратимом удалении сообщения:
protected override async Task OnTeamsMessageSoftDeleteAsync(ITurnContext<IMessageDeleteActivity> turnContext, CancellationToken cancellationToken)
{
var replyActivity = MessageFactory.Text("message is soft deleted");
await turnContext.SendActivityAsync(replyActivity, cancellationToken);
}
Отправка предлагаемых действий
Предлагаемые действия позволяют боту предоставлять кнопки, которые пользователь может выбрать для ввода данных. Предлагаемые действия улучшают взаимодействие с пользователем, позволяя пользователю отвечать на вопрос или делать выбор с помощью кнопки, а не вводить ответ с помощью клавиатуры. Когда пользователь нажимает кнопку, она остается видимой и доступной в расширенных карточках, но не для предлагаемых действий. Это не позволяет пользователю выбирать устаревшие кнопки в беседе.
Чтобы добавить предлагаемые действия в сообщение, задайте suggestedActions
свойство объекта действия , чтобы указать список объектов действия с карточками , которые представляют кнопки, которые будут представлены пользователю. Дополнительные сведения см. в статье sugestedActions
.
Ниже приведен пример реализации и опыта предлагаемых действий.
"suggestedActions": {
"actions": [
{
"type": "imBack",
"title": "Action 1",
"value": "Action 1"
},
{
"type": "imBack",
"title": "Action 2",
"value": "Action 2"
}
],
"to": [<list of recepientIds>]
}
Ниже показан пример предлагаемых действий.
Примечание.
-
SuggestedActions
поддерживаются только для чат-ботов с текстовыми сообщениями и адаптивными карточками. -
SuggestedActions
не поддерживаются для чат-ботов с вложениями для любого типа беседы. -
imBack
— это единственный поддерживаемый тип действия, и Teams отображает до шести предлагаемых действий.
Данные канала Teams
Объект channelData
содержит сведения, относящиеся к Teams, и является окончательным источником идентификаторов команд и каналов. При необходимости эти идентификаторы можно кэшировать и использовать в качестве ключей для локального хранилища. В TeamsActivityHandler
пакете SDK извлекает важную информацию из channelData
объекта, чтобы сделать его доступным. Однако вы всегда можете получить доступ к исходным данным из turnContext
объекта .
Объект channelData
не включается в сообщения в личных беседах, так как они происходят за пределами канала.
Типичный channelData
объект в действии, отправляемом боту, содержит следующие сведения:
-
eventType
: тип события Teams передается только в случаях изменения канала. -
tenant.id
: идентификатор клиента Microsoft Entra, передаваемый во всех контекстах. -
team
: передается только в контекстах канала, а не в личном чате.-
id
: GUID для канала. -
name
: имя команды, переданное только в случаях переименования команды.
-
-
channel
: передается только в контекстах каналов, когда упоминается бот, или для событий в каналах в командах, где бот добавляется.-
id
: GUID для канала. -
name
: имя канала передается только в случаях изменения канала.
-
-
channelData.teamsTeamId
:Устаревшие. Это свойство включается только для обеспечения обратной совместимости. -
channelData.teamsChannelId
:Устаревшие. Это свойство включается только для обеспечения обратной совместимости.
Пример объекта channelData
В следующем коде показан пример объекта channelData (событие channelCreated):
"channelData": {
"eventType": "channelCreated",
"tenant": {
"id": "72f988bf-86f1-41af-91ab-2d7cd011db47"
},
"channel": {
"id": "19:693ecdb923ac4458a5c23661b505fc84@thread.skype",
"name": "My New Channel"
},
"team": {
"id": "19:693ecdb923ac4458a5c23661b505fc84@thread.skype"
}
}
Содержимое сообщения
Сообщения, полученные от бота или отправляемые ей, могут содержать различные типы содержимого сообщений.
Формат | От пользователя к боту | От бота к пользователю | Примечания |
---|---|---|---|
Форматированный текст | ✔️ | ✔️ | Бот может отправлять форматированный текст, изображения и карточки. Пользователи могут отправлять боту форматированный текст и изображения. |
Изображения | ✔️ | ✔️ | Максимум 1024 × 1024 пикселя и 1 МБ в формате PNG, JPEG или GIF. Не поддерживает анимированный GIF-файл. |
Карточки | ❌ | ✔️ | Поддерживаемые карточки см. в справочнике по карточкам Teams . |
Эмодзи | ✔️ | ✔️ | Teams поддерживает эмодзи через UTF-16, например U+1F600 для улыбки лица. |
Сообщения с картинкой
Чтобы улучшить сообщение, можно добавить изображения в виде вложений к сообщению. Дополнительные сведения о вложениях см. в статье Добавление мультимедийных вложений в сообщения.
Изображения могут иметь не более 1024 × 1024 пикселей и 1 МБ в формате PNG, JPEG или GIF. GIF с анимацией не поддерживается.
Укажите высоту и ширину каждого изображения с помощью XML. В Markdown размер изображения по умолчанию — 256×256. Например:
- Используйте:
<img src="http://aka.ms/Fo983c" alt="Duck on a rock" height="150" width="223"></img>
. - Не используйте:
![Duck on a rock](http://aka.ms/Fo983c)
.
Бот беседы может включать адаптивные карточки, которые упрощают бизнес-процессы. Адаптивные карточки предоставляют расширенные настраиваемые текст, речь, изображения, кнопки и поля ввода.
Адаптивные карточки
Адаптивные карточки можно создать в боте и отображать в нескольких приложениях, таких как Teams, ваш веб-сайт и т. д. Дополнительные сведения см. в разделе Адаптивные карточки.
В следующем коде показан пример отправки простой адаптивной карточки:
{
"type": "AdaptiveCard",
"$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
"version": "1.5",
"body": [
{
"items": [
{
"size": "large",
"text": " Simple Adaptivecard Example with a Textbox",
"type": "TextBlock",
"weight": "bolder",
"wrap": true
},
],
"spacing": "extraLarge",
"type": "Container",
"verticalContentAlignment": "center"
}
]
}
Добавление уведомлений в сообщение
Отправить уведомление из приложения можно двумя способами:
- Задав
Notification.Alert
свойство в сообщении бота. - Отправка уведомления веб-канала действий с помощью API Graph.
Вы можете добавить уведомления в сообщение с помощью Notification.Alert
свойства . Уведомления оповещают пользователей о событии в приложении, например о новых задачах, упоминаниях или комментариях. Эти оповещения связаны с тем, над чем работают пользователи или что они должны смотреть, вставляя уведомление в веб-канал действий. Чтобы уведомления активируются из сообщения бота TeamsChannelData
, задайте для свойства objects Notification.Alert
значение true. Если возникает уведомление, это зависит от параметров Teams отдельного пользователя, и вы не можете переопределить эти параметры.
Если вы хотите создать произвольное уведомление, не отправляя пользователю сообщение, можно использовать API Graph. Дополнительные сведения см. в статье Отправка уведомлений веб-канала действий с помощью API Graph и рекомендации.
Примечание.
В поле Сводка отображается любой текст от пользователя в виде уведомления в веб-канале.
В следующем коде показан пример добавления уведомлений в сообщение:
protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
{
// Returns a simple text message.
var message = MessageFactory.Text("You'll get a notification, if you've turned them on.");
message.TeamsNotifyUser();
// Sends an activity to the sender of the incoming activity.
await turnContext.SendActivityAsync(message);
}
Коды состояния из интерфейсов API бесед бота
Обеспечьте соответствующую обработку этих ошибок в приложении Teams. В следующей таблице перечислены коды ошибок и описания, при которых создаются ошибки.
Код состояния | Код ошибки и значения сообщений | Описание | Повторный запрос | Действие разработчика |
---|---|---|---|---|
400 |
Код: Bad Argument Сообщение: *сценарий |
Недопустимые полезные данные запроса, предоставляемые ботом. Дополнительные сведения см. в сообщении об ошибке. | Нет | Переоценка полезных данных запроса на наличие ошибок. Проверьте возвращенное сообщение об ошибке для получения дополнительных сведений. |
401 |
Код: BotNotRegistered Сообщение. Регистрация для этого бота не найдена. |
Регистрация этого бота не найдена. | Нет | Проверьте идентификатор и пароль бота. Убедитесь, что идентификатор бота (Идентификатор Microsoft Entra) зарегистрирован на портале разработчика Teams или через регистрацию канала бота Azure в Azure с включенным каналом Teams. |
403 |
Код: BotDisabledByAdmin Сообщение. Администратор клиента отключил этот бот |
Администратор клиента заблокировал взаимодействие между пользователем и приложением бота. Администратор клиента должен разрешить использование приложения для пользователя в политиках приложений. Дополнительные сведения см. в разделе Политики приложений. | Нет | Остановите публикацию в беседе до тех пор, пока пользователь явно не инициирует взаимодействие с ботом, указывая, что бот больше не заблокирован. |
403 |
Код: BotNotInConversationRoster Сообщение. Бот не входит в список бесед. |
Бот не является частью беседы. Приложение необходимо переустановить в беседе. | Нет | Перед отправкой другого запроса на беседу подождите installationUpdate событие, указывающее на то, что бот будет добавлен снова. |
403 |
Код: ConversationBlockedByUser Сообщение. Пользователь заблокировал беседу с ботом. |
Пользователь заблокировал бот в личном чате или канале с помощью параметров модерации. | Нет | Удалите беседу из кэша. Остановите попытки публикации в беседах, пока пользователь явно не инициирует взаимодействие с ботом, указывая, что бот больше не заблокирован. |
403 |
Код: ForbiddenOperationException Сообщение. Бот не установлен в личной области пользователя |
Упреждающее сообщение отправляется ботом, который не устанавливается в личной области. | Нет | Перед отправкой другого запроса на беседу установите приложение в личной области. |
403 |
Код: InvalidBotApiHost Сообщение: Недопустимый узел API бота. Для клиентов GCC вызовите https://smba.infra.gcc.teams.microsoft.com . |
Бот назвал общедоступную конечную точку API для беседы, которая принадлежит клиенту GCC. | Нет | Обновите URL-адрес службы для беседы https://smba.infra.gcc.teams.microsoft.com и повторите запрос. |
403 |
Код: NotEnoughPermissions Сообщение: *сценарий |
У бота нет необходимых разрешений для выполнения запрошенного действия. | Нет | Определите требуемое действие из сообщения об ошибке. |
404 |
Код: ActivityNotFoundInConversation Сообщение: беседа не найдена. |
Указанный идентификатор сообщения не найден в беседе. Сообщение не существует или удаляется. | Нет | Проверьте, является ли идентификатор отправленного сообщения ожидаемым значением. Удалите идентификатор, если он был кэширован. |
404 |
Код: ConversationNotFound Сообщение: беседа не найдена. |
Беседа не найдена, так как она не существует или удалена. | Нет | Проверьте, является ли отправленный идентификатор беседы ожидаемым значением. Удалите идентификатор, если он был кэширован. |
412 |
Код: PreconditionFailed Сообщение. Сбой предварительного условия, повторите попытку. |
Сбой предварительного условия для одной из зависимостей из-за нескольких одновременных операций в одном диалоге. | Да | Повторите попытку с экспоненциальной задержкой. |
413 |
Код: MessageSizeTooBig Сообщение: слишком большой размер сообщения. |
Размер входящего запроса был слишком велик. Дополнительные сведения см. в разделе Форматирование сообщений бота. | Нет | Уменьшите размер полезных данных. |
429 |
Код: Throttled Сообщение: Слишком много запросов. Также возвращает время повторной попытки после. |
Слишком много запросов, отправленных ботом. Дополнительные сведения см. в разделе Ограничение скорости. | Да | Повторите попытку с помощью Retry-After заголовка для определения времени отката. |
500 |
Код: ServiceError Сообщение: *различные |
Внутренняя ошибка сервера. | Нет | Сообщите о проблеме в сообществе разработчиков. |
502 |
Код: ServiceError Сообщение: *различные |
Проблема с зависимостью службы. | Да | Повторите попытку с экспоненциальной задержкой. Если проблема не исчезнет, сообщите о ней в сообществе разработчиков. |
503 | Служба недоступна. | Да | Повторите попытку с экспоненциальной задержкой. Если проблема не исчезнет, сообщите о ней в сообществе разработчиков. | |
504 | Время ожидания шлюза. | Да | Повторите попытку с экспоненциальной задержкой. Если проблема не исчезнет, сообщите о ней в сообществе разработчиков. |
Руководство по повторным попыткам кодов состояния
Общие рекомендации по повторным попыткам для каждого кода состояния перечислены в следующей таблице. Бот должен избегать повторных попыток кодов состояния, которые не указаны:
Код состояния | Стратегия повторных попыток |
---|---|
403 | Повторите попытку, вызвав API https://smba.infra.gcc.teams.microsoft.com GCC для InvalidBotApiHost . |
412 | Повторите попытку с экспоненциальной задержкой. |
429 | Повторите попытку с помощью Retry-After заголовка, чтобы определить время ожидания в секундах и между запросами, если доступно. В противном случае повторите попытку с экспоненциальной задержкой с идентификатором потока, если это возможно. |
502 | Повторите попытку с экспоненциальной задержкой. |
503 | Повторите попытку с экспоненциальной задержкой. |
504 | Повторите попытку с экспоненциальной задержкой. |
Пример кода
Название примера | Описание | Node.js | .NETCore | Python | .NET | Манифест |
---|---|---|---|---|---|---|
Бот для беседы в Teams | В этом примере приложения показано, как использовать различные события бесед бота, доступные в Bot Framework версии 4. | Просмотр | Просмотр | Просмотр | Н/Д | Просмотр |
Локализация приложений Teams | В этом примере показана локализация приложений Teams с помощью бота и вкладки. | Просмотр | Недоступно | Недоступно | Просмотр | Н/Д |
Следующее действие
См. также
Platform Docs