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

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

Основные беседы обрабатываются через соединитель 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)
{
  // Sends an activity to the sender of the incoming activity.
  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)
{
  // Sends an activity to the sender of the incoming activity.
  await turnContext.SendActivityAsync(MessageFactory.Text($"Hello and welcome!"), cancellationToken);
}

Примечание.

  • Разделение сообщений происходит, когда текстовое сообщение и вложение отправляются в одной и той же полезной нагрузке действия. Teams разделяет это действие на два отдельных действия: одно с текстовым сообщением, а другое с вложением. Так как действие разделено, вы не получаете в ответ идентификатор сообщения, который используется для упреждающего обновления или удаления сообщения. Вместо разбиения сообщений рекомендуется отправлять отдельные действия.
  • Отправленные сообщения можно локализовать для обеспечения персонализации. Дополнительные сведения см. в статье Локализация приложения.

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

Отправка предлагаемых действий

Предлагаемые действия позволяют боту предоставлять кнопки, которые пользователь может выбрать для ввода данных. Предлагаемые действия улучшают взаимодействие с пользователем, позволяя пользователю отвечать на вопрос или делать выбор с помощью кнопки, а не вводить ответ с помощью клавиатуры. Когда пользователь нажимает кнопку, она остается видимой и доступной в расширенных карточках, но не для предлагаемых действий. Это не позволяет пользователю выбирать устаревшие кнопки в беседе.

Чтобы добавить предлагаемые действия в сообщение, задайте 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 поддерживаются только для чат-ботов и текстовых сообщений, но не для адаптивных карточек или вложений.
  • imBack — это единственный поддерживаемый тип действия, и Teams отображает до трех предлагаемых действий.

Данные канала 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 поддерживает эмодзи через 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"
    }
    ]
}

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

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

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

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

  • Успешно. При успешном выполнении ответа, отправленного боту, появится сообщение о том, что ваш ответ отправлен в приложение .

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

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

    Если вы не хотите отображать сообщение об успешном выполнении, задайте атрибуту hide значение true в свойстве msTeamsfeedback . Ниже приведен пример:

       "content": {
           "type": "AdaptiveCard",
           "title": "Card with hidden footer messages",
           "version": "1.0",
           "actions": [
           {
               "type": "Action.Submit",
               "title": "Submit",
               "msTeams": {
                   "feedback": {
                   "hide": true
                   }
               }
           }
           ]
       } 
    

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

Добавление уведомлений в сообщение

Отправить уведомление из приложения можно двумя способами:

  • Задав свойство в 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
Сообщение. Регистрация для этого бота не найдена.
Регистрация этого бота не найдена. Нет Проверьте идентификатор и пароль бота. Убедитесь, что идентификатор бота (идентификатор AAD) зарегистрирован на портале разработчика Teams или через регистрацию канала бота Azure в Azure с включенным каналом Teams.
403 Код: BotDisabledByAdmin
Сообщение. Администратор клиента отключил этот бот
Администратор клиента заблокировал взаимодействие между пользователем и приложением бота. Администратор клиента должен разрешить использование приложения для пользователя в политиках приложений. Дополнительные сведения см. в разделе Политики приложений. Нет Остановите публикацию в беседе, пока пользователь явно не инициирует взаимодействие с ботом, указывая, что бот больше не заблокирован.
403 Код: BotNotInConversationRoster
Сообщение. Бот не входит в список бесед.
Бот не является частью беседы. Приложение необходимо переустановить в беседе. Нет Перед отправкой другого запроса на беседу installationUpdate подождите событие, указывающее на то, что бот был добавлен повторно.
403 Код: ConversationBlockedByUser
Сообщение. Пользователь заблокировал беседу с ботом.
Пользователь заблокировал бот в личном чате или канале с помощью параметров модерации. Нет Удалите беседу из кэша. Остановите попытки публикации в беседах, пока пользователь явно не инициирует взаимодействие с ботом, указывая, что бот больше не заблокирован.
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 Обработка сообщений и бесед. View Просмотр Просмотр Н/Д
Локализация приложений Teams Локализация приложений Teams с помощью бота и вкладки. Просмотр Недоступно Недоступно Просмотр

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

См. также