team: sendActivityNotification

  • Artículo

Espacio de nombres: microsoft.graph

Enviar una notificación de fuente de actividad en el ámbito de un equipo. Para obtener más información sobre el envío de notificaciones y los requisitos para hacerlo, consulte envío de notificaciones de actividad de Teams.

Esta API está disponible en las siguientes implementaciones nacionales de nube.

Servicio global Gobierno de EE. UU. L4 Us Government L5 (DOD) China operada por 21Vianet
✅ ✅ ✅ ❌

Permissions

Elija el permiso o los permisos marcados como con privilegios mínimos para esta API. Use un permiso o permisos con privilegios superiores solo si la aplicación lo requiere. Para obtener más información sobre los permisos delegados y de aplicación, consulte Tipos de permisos. Para obtener más información sobre estos permisos, consulte la referencia de permisos.

Tipo de permiso Permisos con privilegios mínimos Permisos con privilegios más altos
Delegado (cuenta profesional o educativa) TeamsActivity.Send No disponible.
Delegado (cuenta personal de Microsoft) No admitida. No admitida.
Aplicación TeamsActivity.Send.Group TeamsActivity.Send

Nota:

El permiso TeamsActivity.Send.Group usa el consentimiento específico del recurso.

Solicitud HTTP

POST /teams/{teamId}/sendActivityNotification

Encabezados de solicitud

Nombre Descripción
Authorization {token} de portador. Obligatorio. Obtenga más información sobre la autenticación y la autorización.
Content-Type application/json. Obligatorio.

Cuerpo de la solicitud

En el cuerpo de la solicitud, proporcione una representación JSON de los parámetros.

La siguiente tabla muestra los parámetros que se pueden usar con esta acción.

Parámetro Tipo Descripción
topic teamworkActivityTopic Tema de la notificación. Especifica el recurso del que se habla.
activityType Cadena Tipo de actividad. Los tipos de actividad deben declararse en el manifiesto de aplicación de Teams.
chainId Int64 Opcional. Identificador de cadena de la notificación. Se usa para invalidar una notificación anterior. Use lo mismo chainId en solicitudes posteriores para invalidar la notificación anterior.
previewText itemBody Texto de vista previa de la notificación. Microsoft Teams muestra los primeros 150 caracteres.
templateParameters Colección keyValuePair Valores de las variables de plantilla definidas en la entrada de fuente de actividad correspondiente a activityType en el manifiesto de aplicación de Teams.
destinatario teamworkNotificationRecipient Destinatario de la notificación. Para obtener más información, vea aadUserNotificationRecipient, channelMembersNotificationRecipient y teamMembersNotificationRecipient.
teamsAppId Cadena Opcional. El identificador de aplicación de Teams de la aplicación de Teams asociada a la notificación. Se usa para eliminar la ambigüedad de las aplicaciones instaladas cuando se instalan varias aplicaciones con el mismo identificador de aplicación Microsoft Entra ID para el mismo usuario destinatario. Evite compartir Microsoft Entra ID identificadores de aplicación entre aplicaciones de Teams.

Se admiten los siguientes recursos al establecer el source valor de la propiedad topic en entityUrl:

Nota: La dirección URL de la entidad debe ser el mismo recurso secundario del equipo en la dirección URL. Además, la aplicación teams debe estar instalada en el equipo.

Respuesta

Si se ejecuta correctamente, esta acción devuelve un código de respuesta 204 No Content.

Ejemplos

Ejemplo 1: Notificar a un usuario sobre solicitudes de aprobación financiera pendientes

En este ejemplo se muestra cómo puede enviar una notificación de fuente de actividad para un equipo. En este ejemplo se notifica al propietario del equipo sobre las solicitudes de aprobación financiera pendientes.

Solicitud

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": "pendingFinanceApprovalRequests",
    "previewText": {
        "content": "Internal spending team has a pending finance approval requests"
    },
    "recipient": {
        "@odata.type": "microsoft.graph.aadUserNotificationRecipient",
        "userId": "569363e2-4e49-4661-87f2-16f245c5d66a"
    },
    "templateParameters": [
        {
            "name": "pendingRequestCount",
            "value": "5"
        }
    ] 
}

Respuesta

HTTP/1.1 204 No Content

Ejemplo 2: Notificar a un usuario sobre una pestaña de canal

De forma similar al ejemplo anterior, en este ejemplo se usa entityUrl para .topic Sin embargo, en este ejemplo se vincula a una pestaña de un canal. La pestaña hospeda una página que muestra al usuario el estado de su reserva de hotel. La selección de la notificación lleva al usuario a la pestaña, donde puede comprobar su reserva.

Solicitud

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}/channels/{channelId}/tabs/{tabId}"
    },
    "activityType": "reservationUpdated",
    "previewText": {
        "content": "You have moved up the queue"
    },
    "recipient": {
        "@odata.type": "microsoft.graph.aadUserNotificationRecipient",
        "userId": "569363e2-4e49-4661-87f2-16f245c5d66a"
    },
    "templateParameters": [
        {
            "name": "reservationId",
            "value": "TREEE433"
        },
        {
            "name": "currentSlot",
            "value": "23"
        }
    ]
}

Respuesta

HTTP/1.1 204 No Content

Ejemplo 3: Notificar a un usuario sobre una pestaña de canal mediante el nombre principal de usuario

De forma similar al ejemplo anterior, en este ejemplo se usa entityUrl para .topic Sin embargo, en este ejemplo se vincula a una pestaña de un canal. La pestaña hospeda una página que muestra al usuario el estado de su reserva de hotel. La selección de la notificación lleva al usuario a la pestaña, donde puede comprobar su reserva.

Solicitud

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}/channels/{channelId}/tabs/{tabId}"
    },
    "activityType": "reservationUpdated",
    "previewText": {
        "content": "You have moved up the queue"
    },
    "recipient": {
        "@odata.type": "microsoft.graph.aadUserNotificationRecipient",
        "userId": "jacob@contoso.com"
    },
    "templateParameters": [
        {
            "name": "reservationId",
            "value": "TREEE433"
        },
        {
            "name": "currentSlot",
            "value": "23"
        }
    ]
}

Respuesta

HTTP/1.1 204 No Content

Ejemplo 4: Notificar a un usuario sobre un evento mediante un tema personalizado

Como se muestra en los ejemplos anteriores, puede vincular a diferentes aspectos del equipo. Sin embargo, si desea vincular a un aspecto que no forma parte del equipo o no está representado por Microsoft Graph, o si desea personalizar el nombre, puede establecer el origen de en topictext y pasar un valor personalizado para él. webUrl es necesario al establecer el topic origen en text.

Solicitud

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

Respuesta

HTTP/1.1 204 No Content

Ejemplo 5: Notificar a los miembros del equipo sobre solicitudes de aprobación financiera pendientes

En el ejemplo siguiente se muestra cómo enviar una notificación de fuente de actividad a todos los miembros del equipo. Este ejemplo es similar a los ejemplos anteriores. Sin embargo, en este caso, el destinatario es un teamMembersNotificationRecipient. El teamId especificado en el destinatario debe coincidir con el teamId especificado en la dirección URL de la solicitud.

Nota: La capacidad de enviar notificaciones a todos los miembros del equipo se limita a los equipos con 10 000 miembros o menos. Si el equipo supera los 10 000 miembros, ninguno de los miembros del equipo recibirá una notificación.

Solicitud

En el ejemplo siguiente se muestra la solicitud.

POST https://graph.microsoft.com/v1.0/teams/e8bece96-d393-4b9b-b8da-69cedef1a7e7/sendActivityNotification
Content-Type: application/json

{
    "topic": {
        "source": "entityUrl",
        "value": "https://graph.microsoft.com/v1.0/teams/e8bece96-d393-4b9b-b8da-69cedef1a7e7"
    },
    "activityType": "pendingFinanceApprovalRequests",
    "previewText": {
        "content": "Internal spending team has a pending finance approval requests"
    },
    "recipient": {
        "@odata.type": "microsoft.graph.teamMembersNotificationRecipient",
        "teamId": "e8bece96-d393-4b9b-b8da-69cedef1a7e7"
    },
    "templateParameters": [
        {
            "name": "pendingRequestCount",
            "value": "5"
        }
    ] 
}

Respuesta

En el ejemplo siguiente se muestra la respuesta.

HTTP/1.1 204 No Content

Ejemplo 6: Notificar a los miembros del canal sobre solicitudes de aprobación financiera pendientes

En el ejemplo siguiente se muestra cómo enviar una notificación de fuente de actividad a todos los miembros del canal. Este ejemplo es similar al ejemplo anterior. Sin embargo, en este caso, el destinatario es un channelMembersNotificationRecipient. El teamId especificado en el destinatario debe coincidir con el teamId especificado en la dirección URL de la solicitud.

Solicitud

En el ejemplo siguiente se muestra la solicitud.

POST https://graph.microsoft.com/v1.0/teams/e8bece96-d393-4b9b-b8da-69cedef1a7e7/sendActivityNotification
Content-Type: application/json

{
    "topic": {
        "source": "entityUrl",
        "value": "https://graph.microsoft.com/v1.0/teams/e8bece96-d393-4b9b-b8da-69cedef1a7e7"
    },
    "activityType": "pendingFinanceApprovalRequests",
    "previewText": {
        "content": "Internal spending team has a pending finance approval requests"
    },
    "recipient": {
        "@odata.type": "microsoft.graph.channelMembersNotificationRecipient",
        "teamId": "e8bece96-d393-4b9b-b8da-69cedef1a7e7",
        "channelId": "19:3d61a2309f094f4a9310b20f1db37520@thread.tacv2"
    },
    "templateParameters": [
        {
            "name": "pendingRequestCount",
            "value": "5"
        }
    ] 
}

Respuesta

En el ejemplo siguiente se muestra la respuesta.

HTTP/1.1 204 No Content

Ejemplo 7: Notificación sobre solicitudes de aprobación financiera pendientes en la ubicación de respuesta del mensaje de canal

De forma similar al ejemplo anterior, en este ejemplo se usa entityUrl para .topic Sin embargo, en este ejemplo se vincula a una respuesta de mensaje de canal. La respuesta del mensaje de canal muestra el estado de la reserva de hotel del usuario. Al seleccionar la notificación, el usuario se lleva al mensaje de respuesta en el canal, donde puede comprobar su estado de reserva.

Solicitud

En el ejemplo siguiente se muestra la solicitud.

POST https://graph.microsoft.com/v1.0/teams/e8bece96-d393-4b9b-b8da-69cedef1a7e7/sendActivityNotification
Content-Type: application/json

{
    "topic": {
        "source": "entityUrl",
        "value": "https://graph.microsoft.com/beta/teams/{teamId}/channels/{channelId}/messages/{messageId}/replies/{replyId}"
    },
    "activityType": "reservationStatusUpdated",
    "previewText": {
        "content": "You have moved up the queue"
    },
    "recipient": {
        "@odata.type": "microsoft.graph.aadUserNotificationRecipient",
        "userId": "jacob@contoso.com"
    },
    "templateParameters": [
        {
            "name": "reservationId",
            "value": "TREEE433"
        },
        {
            "name": "currentSlot",
            "value": "23"
        }
    ]
}

Respuesta

En el ejemplo siguiente se muestra la respuesta.

HTTP/1.1 204 No Content

Contenido relacionado