Отправка уведомлений веб-канала действий пользователям в Microsoft Teams

Веб-канал действий Microsoft Teams позволяет пользователям рассматривать элементы, требующие внимания, уведомляя их об изменениях. Вы можете использовать API-интерфейсы уведомлений веб-канала действий в Microsoft Graph, чтобы расширить эту функцию для приложений. Это позволяет вашим приложениям предоставлять более широкие возможности и лучше привлекать пользователей, помогая поддерживать их в актуальном состоянии с учетом изменений в используемых ими средствах и рабочих процессах.

Варианты использования уведомлений веб-канала действий

• Новости. Помогает пользователям оставаться в курсе последних сведений, таких как новые назначения или новые публикации.
• Совместная работа. При совместном использовании файла или @упоминание пользователя в комментарии пользователи могут увидеть предварительный просмотр текста в баннере уведомления.
• Напоминания: уведомление, уведомляющее вас о событии или задаче. Например, у вас есть дата выполнения обучения сегодня, и приложение отправляет вам уведомление с напоминанием, чтобы помочь вам запомнить задачу или событие.
• Оповещения: уведомления, требующие срочного или немедленного внимания. Например, истек срок выполнения обучения или администратор направил запрос на исправление ошибки с наивысшим приоритетом.

Преимущества уведомлений веб-канала действий

• Уведомление веб-канала действий — это встроенная интеграция Teams, которая легко переносит пользователя в приложение tab, что приводит к дополнительному взаимодействию пользователей из действия в вашем приложении.
• Уведомление веб-канала действий поставляется с уведомлением ОС в настольных и мобильных клиентах Teams, поэтому внимание пользователей захватывается из системного всплывающего окна и звука.
• Содержимое уведомлений легко настраивается, что позволяет пользователям просматривать сводку оповещенных событий.
• Вы можете связать приложение с уведомлением, чтобы, когда пользователь выбирает уведомление, оно увеличивает вовлеченность пользователей в приложение.
• Вы можете отправлять уведомления о веб-канале действий различным получателям. Например, отправка личного уведомления или пакетных уведомлений группе пользователей.
• Локализация манифеста приложения (ранее называемого манифестом приложения Teams) поддерживает шаблонный текст в уведомлениях веб-канала действий.

Основные сведения об уведомлениях веб-канала действий

В Teams уведомления веб-канала действий состоят из нескольких битов информации, отображаемой вместе, как показано на следующем рисунке:

К компонентам относятся:

Счетчик	Описание
1	Аватар: показывает, кто инициировал действие.
2	Значок типа действия или приложения. Тип действия или значок приложения отображает тип действия. Для уведомлений приложений значок строки заменяется значком приложения.
3	Заголовок: Субъект + причина: Субъект: Имя пользователя или приложения, которые инициировали действие. Причина: описывает действие.
4	Метка времени: показывает, когда произошло действие.
5	Предварительный просмотр текста: отображает усеченную строку от начала уведомления.
6	Расположение: показывает, где произошло действие в Teams.

В следующем примере показаны компоненты вместе с подробными сведениями об уведомлении.

Типы карточек уведомлений веб-канала действий

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

Компьютер

Счетчик	Описание
1	Пользовательское приложение Teams
2	Windows
3	Mac

Мобильные устройства

Счетчик	Описание
1	Android
2	iOS

Требования к использованию API уведомлений канала действий

API веб-канала действий работают с приложением Teams. Ниже приведены требования к отправке уведомлений веб-канала действий.

• Манифест приложения должен иметь Microsoft Entra идентификатор приложения, добавленный в webApplicationInfo раздел. Дополнительные сведения см. в разделе Схема манифеста приложения.
• Уведомления об активности можно отправлять с типами действий, добавленными в манифест приложения, или без нее.
  • По умолчанию можно использовать API-интерфейсы уведомлений о действиях, не добавляя activities раздел в манифест приложения. Тип systemDefault действия зарезервирован, что позволяет предоставить текст в свободной форме в строке Actor+Reason уведомления веб-канала действий. Дополнительные сведения см. в статье Отправка уведомлений настраиваемого веб-канала действий.

    Примечание.

    Тип systemDefault действия доступен только в общедоступной предварительной версии для разработчиков.

  • Если вы хотите отправить шаблонное уведомление в традиционном activityTypes режиме, свойство должно быть добавлено в раздел действия . Дополнительные сведения см. в разделе Схема манифеста приложения.
• Приложение Teams должно быть установлено для получателя лично, в команде или чате, в котором он участвует.

Разрешения

Используйте делегированные разрешения или разрешения приложения для отправки уведомлений веб-канала действий. При использовании разрешений приложения рекомендуется использовать согласие для конкретных ресурсов (RSC), так как TeamsActivity.Send.User пользователь дает согласие на отправку уведомлений о действиях. Обязательно добавьте разрешения RSC в файл манифеста приложения.

Обновление манифеста приложения

В этом разделе описаны обновления, которые необходимо добавить в манифест приложения. Убедитесь, что вы используете версию манифеста приложения или более позднюю версию 1.7 .

"$schema": "https://developer.microsoft.com/json-schemas/teams/v1.7/MicrosoftTeams.schema.json",
"manifestVersion": "1.7",

обновление webApplicationInfo

"webApplicationInfo":
{
    "id": "a3111f15-658e-457c-9689-fd20fe907330",
    "resource": "https://contosoapp.com"
}

Параметр	Тип	Описание
id	string	Microsoft Entra идентификатор приложения (идентификатор клиента).
resource	string	Ресурс, связанный с приложением Microsoft Entra. Также называется URL-адресом ответа или перенаправления на портале Microsoft Azure.

Примечание.

Если несколько приложений Teams в одной область (команда, чат или пользователь) используют одно и то же приложение Microsoft Entra, может возникнуть ошибка. Убедитесь, что вы используете уникальные приложения Microsoft Entra.

Обновление действий

"activities":
{
  "activityTypes": [
    {
      "type": "taskCreated",
      "description": "Task Created Activity",
      "templateText": "{actor} created task {taskId} for you"
    },
    {
      "type": "approvalRequired",
      "description": "Deployment requires your approval",
      "templateText": "{actor} created a new deployment {deploymentId}"
    }
  ]
}

Параметр	Тип	Описание
type	string	Тип действия. Он должен быть уникальным в манифесте определенного приложения.
description	string	Понятное краткое описание. Это отображается в клиенте Teams.
templateText	string	Текст шаблона для уведомления о действии. Параметры можно добавить, инкапсулируя параметры в {}.

Примечание.

• — actor это специальный параметр, который всегда принимает имя вызывающего объекта. В делегированных вызовах actor — имя пользователя. В вызовах только для приложений оно принимает имя приложения Teams.
• Зарезервированный systemDefault тип действия не должен включаться в activities раздел манифеста приложения. Тип systemDefault действия позволяет предоставить текст в свободной форме в строке Actor+Reason уведомления веб-канала действий.

Обновление авторизации

"authorization": 
{ 
  "permissions": { 
    "resourceSpecific": [ 
      {
        "type": "Application", 
         "name": "TeamsActivity.Send.User" 
      }, 
      { 
        "type": "Application",
        "name": "TeamsActivity.Send.Group"
      }, 
      { 
        "type": "Application", 
        "name": "TeamsActivity.Send.Chat" 
      } 
    ] 
  }
}

Параметр	Тип	Описание
type	string	Тип разрешения RSC.
name	string	Имя разрешения RSC. Дополнительные сведения см. в разделе Поддерживаемые разрешения RSC.

Установка приложения Teams

Приложения Teams должны быть установлены в команде, чате или для пользователя в личных область, чтобы пользователи получали уведомления веб-канала действий. Дополнительные сведения см. в разделе Методы распространения приложений Teams. В целях разработки мы предпочитаем отправку пользовательских приложений. После разработки вы можете выбрать правильный метод распространения в зависимости от того, хотите ли вы опубликовать в одном клиенте или во всех клиентах.

Вы также можете использовать API установки приложений Teams для управления установкой приложений Teams.

Отправка уведомлений о веб-канале действий пользователям

Так как приложение Teams можно установить для пользователя, в команде или в чате, оно также может отправлять уведомления в следующих трех контекстах:

• Отправка уведомления пользователю в чате
• Отправка уведомления пользователю в команде
• Отправка уведомления пользователю

Кроме того, вы можете отправлять уведомления массово до 100 пользователей одновременно:

• Массовая отправка уведомлений нескольким пользователям

Сведения о поддерживаемых темах для каждого сценария см. в конкретных API. Пользовательские текстовые разделы поддерживаются во всех сценариях.

Уведомления веб-канала действий можно использовать в следующих сценариях:

• Уведомляйте пользователей о настраиваемом содержимом, которое требует их внимания.
• Отображение полнофункционированного содержимого в приложении tab или URL-адресе.
• Поддержка сложных взаимодействий с пользователем.
• Отправка делегированных уведомлений от пользователя, который инициировал уведомление.
• Поместите шаблон в манифест приложения.
• Teams обрабатывает локализацию уведомлений.

Примечание.

Значок действия основан на контексте, в который выполняется запрос. Если запрос выполняется с делегированными разрешениями, фотография пользователя отображается в качестве аватара, а значок приложения Teams — в качестве значка действия. В контексте только приложения в качестве аватара используется значок приложения Teams, а значок действия опущен.

Настройка уведомлений

Пользователи Teams могут настраивать уведомления, которые они видят в веб-канале или в виде баннера. Уведомления, созданные с помощью API веб-канала действий, также можно настроить. Пользователи могут выбирать способ уведомления с помощью параметров в Teams. Приложения Teams отображаются в списке для выбора пользователем, как показано на следующем снимке экрана:

Пользователи могут выбрать Изменить рядом с приложением и настроить уведомления. В манифесте приложения отображается description поле .

Примеры

Примеры отправки уведомления веб-канала действий см. в разделе Примеры уведомлений о отправке веб-канала действий.

Зарезервированный тип действия для отправки уведомлений веб-канала действий

• Тип systemDefault действия зарезервирован и не может использоваться в манифесте приложения при добавлении действий.
• Рекомендуется использовать шаблонные уведомления, так как они зависят от шаблонов действий в манифесте приложения для повторяющихся и больших пакетов уведомлений.
• Зарезервированный systemDefault тип действия доступен, даже если другие типы действий перечислены в манифесте приложения.

Ниже приведены преимущества и ограничения для systemDefault типа действия.

Преимущества

Ограничения

Вы можете протестировать новые сценарии и попробовать API-интерфейсы уведомлений веб-канала действий, не добавляя типы действий в манифест приложения. С помощью приложений Магазина Teams тип действия упрощает процесс и экономит время, systemDefault так как устраняет необходимость в постоянной корректировке типов действий в манифесте приложения. Тип systemDefault действия готов к использованию немедленно.

Вы не можете использовать встроенные функции локализации, предоставляемые манифестом приложения. Вы не можете полагаться на отправку настраиваемых уведомлений с типом systemDefault действия. Пользователи могут отключить все уведомления из приложения с помощью переключателя в параметрах клиента Teams, что может препятствовать обмену данными между приложением и его пользователями.

Пример кода

Название примера	Описание	.NET	Node.js
Отправка уведомлений ленты новостей	Пример приложения демонстрирует отправку уведомлений веб-канала действий с помощью Microsoft API Graph.	Просмотр	View

Пошаговые инструкции

Следуйте пошаговому руководству, чтобы отправлять уведомления о веб-канале действий в Teams.

См. также

• Бот уведомлений в Teams
• Разработка уведомлений веб-канала действий для приложения Microsoft Teams