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

Каждое сообщение в беседе является Activity объектом типа messageType: message . Когда пользователь отправляет сообщение, Teams отправляет сообщение в бот. Teams отправляет объект JSON в конечную точку обмена сообщениями вашего бота. Бот проверяет сообщение, чтобы определить его тип, и отвечает соответствующим образом.

Основные беседы обрабатываются через соединители Bot Framework, единый API REST. Этот 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, одно с текстовым сообщением, а другое с вложением. При разделении действия в ответ не получается ID сообщения, который используется для обновления или удаления сообщения. Рекомендуется отправлять отдельные действия, а не в зависимости от разделения сообщений.

Сообщения, отправленные между пользователями и ботами, включают внутренние данные канала в сообщении. Эти данные позволяют боту правильно общаться на этом канале. SDK bot Builder позволяет изменять структуру сообщений.

Teams каналов

Объект содержит Teams и является окончательным источником для кодов группы и channelData канала. Дополнительно можно кэширования и использования этих ID в качестве ключей для локального хранения. SDK извлекет важные сведения из объекта, чтобы сделать его TeamsActivityHandler channelData доступным. Однако вы всегда можете получить доступ к исходным данным turnContext объекта.

Объект не входит в сообщения в личных беседах, так как они проходят за channelData пределами канала.

Типичный channelData объект в действии, отправленного боту, содержит следующие сведения:

  • eventType: Teams тип события передается только в случаях событий изменения канала.
  • tenant.id: Azure Active Directory клиента, переданный во всех контекстах.
  • team: Передается только в контекстах каналов, а не в личном чате.
  • 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 для поддерживаемых карт.
Emojis 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);
}

Чтобы улучшить сообщение, вы можете включить изображения в качестве вложений к этому сообщению.

Сообщения изображений

Изображения отправляются путем добавления вложений в сообщение. Дополнительные сведения о вложениях см. в документации Bot Framework.

Изображения могут быть не более 1024×1024 и 1 МБ в формате PNG, JPEG или GIF. Анимированный GIF не поддерживается.

Укажите высоту и ширину каждого изображения с помощью XML. При разметки размер изображения по умолчанию составляет 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"
    }
    ]
}

Дополнительные информацию о картах и картах в ботах см. в документации по картам.

Ответы на код состояния

Ниже печатаются коды состояния и их код ошибок и значения сообщений:

Код состояния Код ошибки и значения сообщений Описание
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

См. также

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