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

  • Статья

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

  • Встроенная интеграция с Teams, которая легко переносит пользователя в приложение Tab и обеспечивает дополнительное взаимодействие пользователей из области действия Teams в вашем приложении.
  • Уведомления операционной системы в классических и мобильных клиентах Teams, включающие всплывающие окна и звук.
  • Настраиваемое содержимое уведомлений, которое позволяет отображать пользователю более или менее предварительное содержимое.
  • Возможность глубоко связать вкладку, личное приложение, сообщение бота или адаптивную карточку с уведомлением, чтобы повысить вовлеченность пользователей в приложение.
  • Возможность отправлять уведомления веб-канала действий нескольким получателям, например пакетные уведомления группе пользователей.

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

API-интерфейсы уведомлений веб-канала действий в Microsoft Graph позволяют использовать следующие варианты использования:

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

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

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

Teams обрабатывает локализацию уведомлений.

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

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

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

В следующей таблице описаны компоненты.

Компонент Описание
Аватар Показывает, кто инициировал действие.
Значок типа действия или приложения Тип действия. Для уведомлений приложений значок строки заменяется значком приложения.
Название: Субъект + причина Субъект — это имя пользователя или приложения, которые инициировали действие. Причина описывает действие.
Timestamp Показывает, когда произошло действие.
Предварительный просмотр текста Отображает усеченную строку от начала уведомления.
Статья Связанный ресурс или текстовое значение раздела из текста запроса.

На следующем рисунке показан пример уведомления веб-канала действий в Teams. В этом примере пользователь предоставил общий доступ к записи в приложении.

Изображение уведомления веб-канала действий Yammer

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

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

Пользовательское приложение Teams

Снимок экрана, на котором показаны уведомления веб-канала действий в пользовательском приложении Teams для настольных компьютеров.

Windows

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

Mac

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

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

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

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

      Примечание.

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

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

Разрешения

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

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

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

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

обновление webApplicationInfo

Необходимо обновить Microsoft Entra id и resource сведения в свойстве манифеста webApplicationInfo приложения.

"webApplicationInfo":
{
    "id": "a3111f15-658e-457c-9689-fd20fe907330",
    "resource": "https://contosoapp.com"
}
Параметр Тип Описание
id string Microsoft Entra (идентификатор клиента).
resource string Ресурс, связанный с приложением Azure AD. Он также называется URI ответа или перенаправления в обзоре регистрации приложений Центр администрирования Microsoft Entra.

Примечание.

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

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

Чтобы опубликовать веб-канал действий пользователя, activities необходимо определить свойство в манифесте приложения.

"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 Понятное краткое описание. Описание отображается в клиенте Microsoft Teams.
templateText string Текст шаблона для уведомления о действии. Параметры можно объявить, инкапсулировав параметры в фигурные скобки {}.

Примечание.

  • actor — это специальный параметр, который всегда принимает имя вызывающего объекта. В делегированных вызовах actor — имя пользователя. В вызовах только для приложений оно принимает имя приложения Teams.

  • Зарезервированный systemDefault тип действия не должен быть указан в activities разделе манифеста. Зарезервированный тип действия может предоставлять текст в свободной форме в строке 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.

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

Примечание.

Чтобы отображать уведомления веб-канала действий на клиентах iOS и Android, приложение должно быть включено в список разрешений. Поддерживаются только сторонние приложения.

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

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

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

Примечание.

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

Пример 1. Уведомление пользователя о задаче, созданной в чате

В следующем примере показано, как отправить уведомление веб-канала действий для новой задачи, созданной в чате. В этом случае приложение Teams должно быть установлено в чате с идентификатором chatId , а пользователь 569363e2-4e49-4661-87f2-16f245c5d66a также должен быть частью чата.

Запрос

POST https://graph.microsoft.com/v1.0/chats/{chatId}/sendActivityNotification
Content-Type: application/json

{
    "topic": {
        "source": "entityUrl",
        "value": "https://graph.microsoft.com/v1.0/chats/{chatId}"
    },
    "activityType": "taskCreated",
    "previewText": {
        "content": "New Task Created"
    },
    "recipient": {
        "@odata.type": "microsoft.graph.aadUserNotificationRecipient",
        "userId": "569363e2-4e49-4661-87f2-16f245c5d66a"
    },
    "templateParameters": [
        {
            "name": "taskId",
            "value": "12322"
        }
    ]
}

Отклик

HTTP/1.1 204 No Content

Пример 2. Уведомление пользователя о задаче, созданной в команде

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

Запрос

POST https://graph.microsoft.com/v1.0/teams/{teamId}/sendActivityNotification
Content-Type: application/json

{
    "topic": {
        "source": "entityUrl",
        "value": "https://graph.microsoft.com/v1.0/teams/{teamId}"
    },
    "activityType": "taskCreated",
    "previewText": {
        "content": "New Task Created"
    },
    "recipient": {
        "@odata.type": "microsoft.graph.aadUserNotificationRecipient",
        "userId": "569363e2-4e49-4661-87f2-16f245c5d66a"
    },
    "templateParameters": [
        {
            "name": "taskId",
            "value": "12322"
        }
    ]
}

Отклик

HTTP/1.1 204 No Content

Пример 3. Уведомление пользователя о событии с помощью пользовательского раздела

Как показано в предыдущих примерах, можно связать с различными аспектами команды или чата. Однако если вы хотите связать с аспектом, который не является частью команды или Microsoft Graph не представляет его, или если вы хотите настроить имя, можно задать источник topictext объекта в и передать для него настраиваемое значение. Кроме того, требуется при webUrl использовании topic источника в качестве text.

В приведенном выше примере уведомления Yammer используется пользовательский раздел, так как Microsoft Graph не поддерживает ресурсы Yammer.

Примечание.

webUrl должен начинаться с домена Microsoft Teams (например, teams.microsoft.com).

Запрос

POST https://graph.microsoft.com/v1.0/teams/{teamId}/sendActivityNotification
Content-Type: application/json

{
    "topic": {
        "source": "text",
        "value": "Deployment Approvals Channel",
        "webUrl": "https://teams.microsoft.com/l/message/19:448cfd2ac2a7490a9084a9ed14cttr78c@thread.skype/1605223780000?tenantId=c8b1bf45-3834-4ecf-971a-b4c755ee677d&groupId=d4c2a937-f097-435a-bc91-5c1683ca7245&parentMessageId=1605223771864&teamName=Approvals&channelName=Azure%20DevOps&createdTime=1605223780000"
    },
    "activityType": "approvalRequired",
    "previewText": {
        "content": "New deployment requires your approval"
    },
    "recipient": {
        "@odata.type": "microsoft.graph.aadUserNotificationRecipient",
        "userId": "569363e2-4e49-4661-87f2-16f245c5d66a"
    },
    "templateParameters": [
        {
            "name": "deploymentId",
            "value": "6788662"
        }
    ]
}

Отклик

HTTP/1.1 204 No Content

Пример 4. Уведомление участников команды о событии

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

Запрос

POST https://graph.microsoft.com/v1.0/teams/7155e3c8-175e-4311-97ef-572edc3aa3db/sendActivityNotification
Content-Type: application/json

{
    "topic": {
        "source": "text",
        "value": "Weekly Virtual Social",
        "webUrl": "https://teams.microsoft.com/l/message/19:448cfd2ac2a7490a9084a9ed14cttr78c@thread.skype/1605223780000?tenantId=c8b1bf45-3834-4ecf-971a-b4c755ee677d&groupId=d4c2a937-f097-435a-bc91-5c1683ca7245&parentMessageId=1605223771864&teamName=Approvals&channelName=Azure%20DevOps&createdTime=1605223780000"
    },
    "previewText": {
        "content": "It will be fun!"
    },
    "activityType": "eventCreated",
    "recipient": {
        "@odata.type": "microsoft.graph.teamMembersNotificationRecipient",
        "teamId": "7155e3c8-175e-4311-97ef-572edc3aa3db"
    }
}

Отклик

HTTP/1.1 204 No Content

Пример 5. Уведомление участников канала о событии

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

Запрос

POST https://graph.microsoft.com/v1.0/teams/7155e3c8-175e-4311-97ef-572edc3aa3db/sendActivityNotification
Content-Type: application/json

{
    "topic": {
        "source": "text",
        "value": "Weekly Virtual Social",
        "webUrl": "https://teams.microsoft.com/l/message/19:448cfd2ac2a7490a9084a9ed14cttr78c@thread.skype/1605223780000?tenantId=c8b1bf45-3834-4ecf-971a-b4c755ee677d&groupId=d4c2a937-f097-435a-bc91-5c1683ca7245&parentMessageId=1605223771864&teamName=Approvals&channelName=Azure%20DevOps&createdTime=1605223780000"
    },
    "previewText": {
        "content": "It will be fun!"
    },
    "activityType": "eventCreated",
    "recipient": {
        "@odata.type": "microsoft.graph.channelMembersNotificationRecipient",
        "teamId": "7155e3c8-175e-4311-97ef-572edc3aa3db",
        "channelId": "19:0ea5de04de4743bcb4cd20cb99235d99@thread.tacv2"
    }
}

Отклик

HTTP/1.1 204 No Content

Пример 6. Уведомление участников чата о событии

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

Запрос

POST https://graph.microsoft.com/v1.0/chats/19:d65713bc498c4a428c71ef9353e6ce20@thread.v2/sendActivityNotification
Content-Type: application/json

{
    "topic": {
        "source": "text",
        "value": "Weekly Virtual Social",
        "webUrl": "https://teams.microsoft.com/l/message/19:448cfd2ac2a7490a9084a9ed14cttr78c@thread.skype/1605223780000?tenantId=c8b1bf45-3834-4ecf-971a-b4c755ee677d&groupId=d4c2a937-f097-435a-bc91-5c1683ca7245&parentMessageId=1605223771864&teamName=Approvals&channelName=Azure%20DevOps&createdTime=1605223780000"
    },
    "previewText": {
        "content": "It will be fun!"
    },
    "activityType": "eventCreated",
    "recipient": {
        "@odata.type": "microsoft.graph.chatMembersNotificationRecipient",
        "chatId": "19:d65713bc498c4a428c71ef9353e6ce20@thread.v2"
    }
}

Отклик

HTTP/1.1 204 No Content

Пример 7. Уведомление нескольких пользователей об ожидающих запросах на утверждение финансов

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

Запрос

POST https://graph.microsoft.com/v1.0/teamwork/sendActivityNotificationToRecipients
Content-Type: application/json

{
    "topic": {
        "source": "entityUrl",
        "value": "https://graph.microsoft.com/v1.0/appCatalogs/teamsApps/{teamsAppId}"
    },
    "activityType": "pendingFinanceApprovalRequests",
    "previewText": {
        "content": "Internal spending team has a pending finance approval requests"
    },
    "recipients": [
        {
            "@odata.type": "microsoft.graph.aadUserNotificationRecipient",
            "userId": "569363e2-4e49-4661-87f2-16f245c5d66a"
        },
        {
            "@odata.type": "microsoft.graph.aadUserNotificationRecipient",
            "userId": "ab88234e-0874-477c-9638-d144296ed04f"
        },
        {
            "@odata.type": "microsoft.graph.aadUserNotificationRecipient",
            "userId": "01c64f53-69aa-42c7-9b7f-9f75195d6bfc"
        }
    ],
    "templateParameters": [
        {
            "name": "pendingRequestCount",
            "value": "5"
        }
    ] 
}

Отклик

HTTP/1.1 202 Accepted

Пример 8. Отправка уведомления пользователю с помощью типа действия systemDefault

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

Примечание.

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

В этом примере владелец команды уведомляет о том, что он должен сделать небольшой перерыв. Измените в value , templateParameters чтобы настроить уведомление для различных сценариев.

Запрос

POST https://graph.microsoft.com/v1.0/teams/{teamId}/sendActivityNotification
Content-Type: application/json

{
    "topic": {
        "source": "entityUrl",
        "value": "https://graph.microsoft.com/v1.0/teams/{teamId}"
    },
    "activityType": "systemDefault",
    "previewText": {
        "content": "Take a break"
    },
    "recipient": {
        "@odata.type": "microsoft.graph.aadUserNotificationRecipient",
        "userId": "569363e2-4e49-4661-87f2-16f245c5d66a"
    },
    "templateParameters": [
        {
            "name": "systemDefaultText",
            "value": "You need to take a short break"
        }
    ]
}

Отклик

HTTP/1.1 204 No Content

Зарезервированные типы действий

Тип systemDefault действия зарезервирован и не может использоваться в манифесте при объявлении действий. Тип действия можно использовать systemDefault для:

  • Легко тестируйте новые сценарии и (или) быстро пробуйте API-интерфейсы уведомлений веб-канала действий без определения типов действий в манифесте приложения.
  • Для приложений Магазина экономьте время и оптимизируйте процесс, так как вам не нужно постоянно настраивать типы действий в манифесте приложения. Тип systemDefault действия готов к использованию из get-go.

Имейте в виду, что с типом systemDefault действия вы не можете:

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

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

Зарезервированный systemDefault тип действия остается доступным независимо от типов действий, перечисленных в манифесте приложения.

Настройка оповещений о том, как уведомления оповещают вас

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

Снимок экрана: параметры уведомлений в Teams с выделенным параметром Custom

Пользователи могут выбрать Изменить рядом с приложением и настроить уведомления, как показано в следующем примере. Отображается description поле в манифесте приложения Teams.

Снимок экрана: уведомления, настроенные для баннера и веб-канала для приложения Teams

Вопросы и ответы

Кому нужно установить приложение Teams?

У целевого пользователя должно быть установлено приложение Teams, которое отправляет уведомления.

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

Нет, пользователь не может отправлять уведомления себе. В этом сценарии используйте разрешения приложения.

Может ли приложение Teams управлять отображением уведомлений для пользователя?

Нет, изменять параметры уведомлений могут только пользователи.

Я установил свое приложение; Почему в учетной записи пользователя не отображаются параметры уведомлений?

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

Я начал получать ошибку 409 (конфликт); как ее устранить?

ConflictОшибки в основном возникают, если несколько приложений Teams, установленных в одном область (команда, чат, пользователь и т. д.), имеют одинаковый Microsoft Entra appId в webApplicationInfo разделе манифеста. В этом случае появляется сообщение об ошибке, например Found multiple applications with the same Microsoft Entra App ID 'Your Microsoft Entra AppId'.. Убедитесь, что вы используете уникальные приложения Microsoft Entra для уникальных приложений Teams. Одно и то же приложение Teams можно установить в нескольких областях (например, команда и пользователь).

Связанные материалы