chat: sendActivityNotification

Пространство имен: microsoft.graph

Отправка уведомления веб-канала действий в область чата. Дополнительные сведения об отправке уведомлений и требованиях для этого см. в статье Отправка уведомлений о действиях Teams.

Этот API доступен в следующих национальных облачных развертываниях.

Глобальная служба Правительство США L4 Правительство США L5 (DOD) Китай управляется 21Vianet
✅ ✅ ✅ ✅

Разрешения

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

Тип разрешения Разрешения с наименьшими привилегиями Более высокие привилегированные разрешения
Делегированные (рабочая или учебная учетная запись) TeamsActivity.Send Недоступно.
Делегированные (личная учетная запись Майкрософт) Не поддерживается. Не поддерживается.
Приложение TeamsActivity.Send.Chat TeamsActivity.Send

Заметка: Разрешение TeamsActivity.Send.Chat использует согласие для конкретного ресурса.

HTTP-запрос

POST /chats/{chatId}/sendActivityNotification

Заголовки запросов

Имя Описание
Авторизация Bearer {token}. Обязательно. Дополнительные сведения о проверке подлинности и авторизации.
Content-Type application/json. Обязательно.

Текст запроса

В тело запроса добавьте параметры в формате JSON.

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

Параметр Тип Описание
activityType String Тип действия должен быть объявлен в манифесте приложения Teams, за systemDefault исключением типа зарезервированного действия, который предоставляет текст в свободной форме в строке Actor+Reason уведомления.
chainId Int64 Необязательный параметр. Идентификатор цепочки уведомления. Используется для переопределения предыдущего уведомления. Используйте то же chainId самое в последующих запросах, чтобы переопределить предыдущее уведомление.
iconId String Необязательный параметр. Уникальный идентификатор значка, позволяющий приложениям отправлять настраиваемые значки для каждого типа действия. Идентификаторы значков должны присутствовать в схеме манифеста приложения Teams. Если идентификатор значка указан в манифесте, но отсутствует в тексте запроса API, значок возвращается к значку по умолчанию для приложения.
previewText itemBody Текст предварительного просмотра для уведомления. В Microsoft Teams отображаются первые 150 символов.
получатель; teamworkNotificationRecipient Получатель уведомления. Дополнительные сведения см. в разделах aadUserNotificationRecipient и chatMembersNotificationRecipient.
teamsAppId String Необязательный параметр. Идентификатор приложения Teams, связанного с уведомлением. Используется для устранения неоднозначности установленных приложений, когда для одного и того же пользователя-получателя установлено несколько приложений с одинаковым Microsoft Entra ID идентификатором приложения. Избегайте совместного использования идентификаторов приложений Microsoft Entra ID между приложениями Teams.
templateParameters Коллекция keyValuePair Значения переменных шаблона, определенных в записи веб-канала действий, activityType соответствующей в манифесте приложения Teams.
topic teamworkActivityTopic Раздел уведомления. Указывает ресурс, о котором идет речь.

Следующие ресурсы поддерживаются при установке source значения свойства раздела в entityURL:

Заметка: URL-адрес сущности должен быть таким же, как или дочерний ресурс чата в URL-адресе. Кроме того, приложение Teams должно быть установлено в чате.

Отклик

В случае успешного выполнения это действие возвращает код отклика 204 No Content.

Примеры

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

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

Запрос

Ниже показан пример запроса.

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": "Task 12322"
        }
    ] 
}

Отклик

Ниже показан пример отклика.

HTTP/1.1 204 No Content

Пример 2. Уведомление пользователя о необходимости утверждения в сообщении чата

Как и в предыдущем примере, в этом примере используется entityUrl для topic. Однако в этом случае он ссылается на сообщение в чате. Сообщение может содержать карта с кнопкой утверждения.

Запрос

Ниже показан пример запроса.

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}/messages/{messageId}"
    },
    "activityType": "approvalRequired",
    "previewText": {
        "content": "Deployment requires your approval"
    },
    "recipient": {
        "@odata.type": "microsoft.graph.aadUserNotificationRecipient",
        "userId": "569363e2-4e49-4661-87f2-16f245c5d66a"
    },
    "templateParameters": [
        {
            "name": "approvalTaskId",
            "value": "2020AAGGTAPP"
        }
    ]
}

Отклик

Ниже показан пример отклика.

HTTP/1.1 204 No Content

Пример 3. Уведомление пользователя о необходимости утверждения в сообщении чата с помощью имени участника-пользователя

Как и в предыдущем примере, в этом примере используется entityUrl для topic. Однако в этом случае он ссылается на сообщение в чате. Сообщение может содержать карта с кнопкой утверждения.

Запрос

Ниже показан пример запроса.

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}/messages/{messageId}"
    },
    "activityType": "approvalRequired",
    "previewText": {
        "content": "Deployment requires your approval"
    },
    "recipient": {
        "@odata.type": "microsoft.graph.aadUserNotificationRecipient",
        "userId": "jacob@contoso.com"
    },
    "templateParameters": [
        {
            "name": "approvalTaskId",
            "value": "2020AAGGTAPP"
        }
    ]
}

Отклик

Ниже показан пример отклика.

HTTP/1.1 204 No Content

Пример 4. Уведомление пользователя о событии в связи с чатом

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

Запрос

Ниже показан пример запроса.

POST https://graph.microsoft.com/v1.0/chats/{chatId}/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": "deploymentApprovalRequired",
    "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

Пример 5. Уведомление участников чата о задаче, созданной в чате

В следующем примере показано, как отправить уведомление о веб-канале действий всем участникам чата. Этот пример аналогичен предыдущим примерам. Однако в этом случае получателем является chatMembersNotificationRecipient. Значение chatId , указанное в получателе , должно соответствовать значению chatId , указанному в URL-адресе запроса.

Запрос

Ниже показан пример запроса.

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

{
    "topic": {
        "source": "entityUrl",
        "value": "https://graph.microsoft.com/v1.0/chats/19:1c3af46e9e0f4a5293343c8813c47619@thread.v2"
    },
    "activityType": "taskCreated",
    "previewText": {
        "content": "New Task Created"
    },
    "recipient": {
        "@odata.type": "microsoft.graph.chatMembersNotificationRecipient",
        "chatId": "19:1c3af46e9e0f4a5293343c8813c47619@thread.v2"
    },
    "templateParameters": [
        {
            "name": "taskId",
            "value": "Task 12322"
        }
    ] 
}

Отклик

Ниже показан пример отклика.

HTTP/1.1 204 No Content

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

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

Заметка: Для activityType использования этого параметра в манифесте должен содержаться список разрешенных идентификаторов значков. Проверка запроса завершается ошибкой, если в манифесте приложения отсутствует настраиваемый список значков. Дополнительные сведения см. в разделе Общедоступная предварительная версия манифеста приложения для разработчиков.

Запрос

Ниже показан пример запроса.

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

{
  "topic": {
    "source": "entityUrl",
    "value": "https://graph.microsoft.com/v1.0/chats/19:1c3af46e9e0f4a5293343c8813c47619@thread.v2"
  },
  "activityType": "taskCreated",
  "previewText": {
    "content": "new task created"
  },
  "iconId": "taskCreatedIcon",
  "recipient": {
    "@odata.type": "microsoft.graph.chatMembersNotificationRecipient",
    "chatId": "19:1c3af46e9e0f4a5293343c8813c47619@thread.v2"
  },
  "templateParameters": [
    {
      "name": "taskId",
      "value": "Task 12322"
    }
  ]
}

Отклик

Ниже показан пример отклика.

HTTP/1.1 204 No Content

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

  • Last updated on