Сообщения в беседах с ботами
Каждое сообщение в беседе является объектом Activity
типа messageType: message
. Когда пользователь отправляет сообщение, Teams отправляет его боту. Teams отправляет объект JSON в конечную точку обмена сообщениями бота. Бот проверяет сообщение, чтобы определить его тип и ответить соответствующим образом.
Основные беседы обрабатываются через соединитель Bot Framework, один REST API. Этот API позволяет боту взаимодействовать с Teams и другими каналами. Пакет SDK Bot Builder предоставляет следующие функции:
- Простой доступ к соединителю Bot Framework.
- Дополнительные функции для управления потоком беседы и состоянием.
- Простые способы внедрения когнитивных служб, таких как обработка естественного языка (NLP).
Бот получает сообщения от Teams с Text
помощью свойства и отправляет пользователям один или несколько ответов на сообщения.
Дополнительные сведения см. в описании атрибутов пользователей для сообщений бота.
Получение сообщения
Чтобы получить текстовое сообщение, используйте свойство Text
объекта Activity
. В обработчике активности бота используйте объект контекста поворота Activity
для чтения одного запроса сообщения.
В следующем коде показан пример получения сообщения:
protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
{
await turnContext.SendActivityAsync(MessageFactory.Text($"Echo: {turnContext.Activity.Text}"), cancellationToken);
}
Отправка сообщения
Чтобы отправить текстовое сообщение, укажите строку, которая будет отправляться в качестве действия. В обработчике действий бота используйте SendActivityAsync
метод объекта контекста шага для отправки одного ответа на сообщение. Используйте метод объекта для SendActivitiesAsync
отправки нескольких ответов одновременно.
В следующем коде показан пример отправки сообщения при добавлении пользователя в беседу:
protected override async Task OnMembersAddedAsync(IList<ChannelAccount> membersAdded, ITurnContext<IConversationUpdateActivity> turnContext, CancellationToken cancellationToken)
{
await turnContext.SendActivityAsync(MessageFactory.Text($"Hello and welcome!"), cancellationToken);
}
Примечание
Разделение сообщений происходит, когда текстовое сообщение и вложение отправляются в тех же полезных данных действия. Это действие разбивается на отдельные действия по Microsoft Teams, одно с текстовым сообщением, а другое с вложением. При разделении действия идентификатор сообщения в ответе не получается, который используется для упреждающего обновления или удаления сообщения. Рекомендуется отправлять отдельные действия, а не в зависимости от разделения сообщений.
Сообщения, отправляемые между пользователями и ботами, включают внутренние данные канала в сообщении. Эти данные позволяют боту правильно обмениваться данными по этому каналу. Пакет SDK Bot Builder позволяет изменять структуру сообщений.
Данные канала Teams
Объект channelData
содержит Teams сведениях, связанных с определенными данными, и является окончательным источником идентификаторов команд и каналов. При необходимости можно кэшировать и использовать эти идентификаторы в качестве ключей для локального хранилища. Пакет TeamsActivityHandler
SDK извлекет важные сведения из channelData
объекта, чтобы сделать его доступным. Однако вы всегда можете получить доступ к исходным данным из turnContext
объекта.
Объект channelData
не включается в сообщения в личных беседах, так как они имеют место за пределами канала.
Типичный channelData
объект в действии, отправляемом боту, содержит следующие сведения:
eventType
: Teams передается только в случае событий изменения канала.tenant.id
: Microsoft Azure Active Directory (Azure AD) идентификатор клиента, переданный во всех контекстах.team
: передается только в контекстах канала, а не в личном чате.id
: GUID для канала.name
: имя команды, переданное только в случае переименования команды.
channel
: передается только в контекстах каналов, когда упоминается бот, или для событий в каналах в командах, в которых был добавлен бот.id
: GUID для канала.name
: имя канала передается только в случае событий изменения канала.
channelData.teamsTeamId
: не рекомендуется. Это свойство включено только для обеспечения обратной совместимости.channelData.teamsChannelId
: не рекомендуется. Это свойство включено только для обеспечения обратной совместимости.
Пример объекта channelData (событие channelCreated)
В следующем коде показан пример объекта channelData:
"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 карточки. |
Эмодзи | ✔️ | ✔️ | Teams в настоящее время поддерживает эмодзи через UTF-16, например U+1F600 для усинхронного распознавания лиц. |
Уведомления в сообщении
Вы также можете добавить уведомления в сообщение с помощью свойства Notification.Alert
. Уведомления предупреждают пользователей о новых задачах, упоминаниях и комментариях. Эти оповещения связаны с тем, над чем работают пользователи или что они должны просмотреть, вставив уведомление в веб-канал активности. Чтобы уведомления запускались из сообщения бота, задайте TeamsChannelData
для свойства объектов Notification.Alert
значение true. Независимо от того, создается ли уведомление, зависит от параметров Teams пользователя, и вы не можете переопределить эти параметры. Тип уведомления — это либо баннер, либо баннер и сообщение электронной почты.
Примечание
В поле "Сводка " в веб-канале отображается любой текст от пользователя в виде уведомления.
В следующем коде показан пример добавления уведомлений в сообщение:
protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
{
var message = MessageFactory.Text("You'll get a notification, if you've turned them on.");
message.TeamsNotifyUser();
await turnContext.SendActivityAsync(message);
}
Чтобы улучшить сообщение, в него можно добавить изображения в виде вложений.
Сообщения с картинкой
Картинки отправляются путем добавления вложений к сообщению. Дополнительные сведения о вложениях см. в разделе "Добавление вложений мультимедиа в сообщения".
Изображения могут иметь не более 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>
. - Не используйте:

.
Чат-бот может включать адаптивные карточки, упрощающие бизнес-процессы. Адаптивные карточки предлагают форматированный настраиваемый текст, речь, изображения, кнопки и поля ввода.
Адаптивные карточки
Адаптивные карточки можно создавать в боте и отображать в нескольких приложениях, таких как 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"
}
]
}
Отзывы о завершении формы
Сообщение о завершении формы отображается в адаптивных карточках при отправке ответа боту. Сообщение может иметь два типа: ошибка или успешное выполнение:
Ошибка. Если ответ, отправленный боту, неуспешно, что-то пошло не так, появится сообщение "Повторить попытку".
Успешно. Когда ответ, отправленный боту, будет успешно отправлен, появится ваш ответ на сообщение приложения.
Вы можете закрыть или переключить чат, чтобы закрыть сообщение.
Если вы не хотите отображать сообщение об успешном выполнении,
hide
задайте атрибут вtrue
свойствеmsTeams
feedback
. Ниже приведен пример:"content": { "type": "AdaptiveCard", "title": "Card with hidden footer messages", "version": "1.0", "actions": [ { "type": "Action.Submit", "title": "Submit", "msTeams": { "feedback": { "hide": true } } } ] }
Дополнительные сведения о карточках и карточках в ботах см. в документации по карточкам.
Ответы на код состояния
Ниже приведены коды состояния и их код ошибки и значения сообщений:
Код состояния | Код ошибки и значения сообщений | Описание |
---|---|---|
403 | Код: ConversationBlockedByUser Сообщение: пользователь заблокируют беседу с ботом. |
Пользователь заблокирует бота в чате 1:1 или канале с помощью параметров модерации. |
403 | Код: BotNotInConversationRoster Сообщение: бот не входит в список бесед. |
Бот не является частью беседы. |
403 | Код: BotDisabledByAdmin Сообщение: администратор клиента отключает этот бот. |
Клиент заблокируют бот. |
401 | Код: BotNotRegistered Сообщение: регистрация для этого бота не найдена. |
Регистрация этого бота не найдена. |
412 | Код: PreconditionFailed Сообщение: Сбой предварительного условия. Повторите попытку. |
Не удалось выполнить предусловие для одной из наших зависимостей из-за нескольких параллельных операций в одной беседе. |
404 | Код: ConversationNotFound Сообщение: беседа не найдена. |
Беседа не найдена. |
413 | Код: MessageSizeTooBig Сообщение: слишком большой размер сообщения. |
Размер входящего запроса был слишком большим. |
429 | Код: Throttled Сообщение: слишком много запросов. Также возвращает время повторной попытки. |
Бот отправил слишком много запросов. Дополнительные сведения см. в разделе "Ограничение скорости". |
Пример кода
Название примера | Описание | .NETCore | Node.js | Python |
---|---|---|---|---|
Бот для беседы в Teams | Обработка сообщений и бесед. | View | View | View |