Compartir a través de

team: sendActivityNotification

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
activityType Cadena El tipo de actividad debe declararse en el manifiesto de aplicación de Teams, excepto para el systemDefaulttipo de actividad Reservada, que proporciona texto de forma libre en la Actor+Reason línea de la notificación.
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.
iconId Cadena Opcional. Identificador de icono único que permite a las aplicaciones enviar iconos personalizados por tipo de actividad. Los identificadores de icono deben estar presentes en el esquema de manifiesto de aplicación de Teams. Si el identificador de icono se especifica en el manifiesto pero falta en el cuerpo de la solicitud de API, el icono vuelve al icono predeterminado de la aplicación.
previewText itemBody Texto de vista previa de la notificación. Microsoft Teams muestra los primeros 150 caracteres.
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.
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.
topic teamworkActivityTopic Tema de la notificación. Especifica el recurso del que se habla.

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/v1.0/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

Ejemplo 8: Notificar a un usuario de un equipo sobre un evento mediante un icono personalizado

Si desea notificar a un usuario de un equipo con un icono personalizado en lugar del icono de aplicación predeterminado, puede establecer la propiedad iconId opcional en el cuerpo de la solicitud.

Nota: En activityType el manifiesto debe contener la lista de identificadores de icono permitidos para poder usar este parámetro. Se produce un error en la validación de la solicitud si falta la lista personalizada de iconos en el manifiesto de la aplicación. Para obtener más información, consulte Manifiesto de aplicación de versión preliminar para desarrolladores públicos.

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/{teamId}/channels/{channelId}/messages/{messageId}/replies/{replyId}"
  },
  "activityType": "announcementPosted",
  "previewText": {
    "content": "new announcemnet posted"
  },
  "iconId": "announcementCreated",
  "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

  • Last updated on