Сообщения в беседах с ботами

Каждое сообщение в беседе является объектом 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: передается только в контекстах канала, а не в личном чате.
  • channel: передается только в контекстах каналов, когда упоминается бот, или для событий в каналах в командах, в которых был добавлен бот.
  • 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>.
  • Не используйте: ![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"
    }
    ]
}

Отзывы о завершении формы

Сообщение о завершении формы отображается в адаптивных карточках при отправке ответа боту. Сообщение может иметь два типа: ошибка или успешное выполнение:

  • Ошибка. Если ответ, отправленный боту, неуспешно, что-то пошло не так, появится сообщение "Повторить попытку".

    Сообщение об ошибке

  • Успешно. Когда ответ, отправленный боту, будет успешно отправлен, появится ваш ответ на сообщение приложения.

    Сообщение об успешном выполнении

    Вы можете закрыть или переключить чат, чтобы закрыть сообщение.

    Если вы не хотите отображать сообщение об успешном выполнении, 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

Следующий этап

См. также