Compartir a través de

Envío de notificaciones de fuente de actividad a usuarios de Microsoft Teams

  • Artículo

La fuente de actividades de Microsoft Teams notifica a los usuarios los cambios para permitirles evaluar los elementos que requieren atención. Las notificaciones de fuente de actividad en Teams incluyen las siguientes características:

  • Integración nativa con Teams que lleva al usuario sin problemas a la aplicación Tab y proporciona una interacción adicional del usuario desde el panel Actividad de Teams a la aplicación.
  • Notificaciones del sistema operativo en clientes móviles y de escritorio de Teams que incluyen un elemento emergente y un sonido.
  • Contenido de notificación personalizable que le permite mostrar más o menos contenido en versión preliminar al usuario.
  • Capacidad de vincular en profundidad la pestaña, la aplicación personal, el mensaje del bot o la tarjeta adaptable a una notificación para aumentar la interacción del usuario con la aplicación.
  • Capacidad de enviar notificaciones de fuente de actividad a varios destinatarios, como notificaciones por lotes a un grupo de usuarios.

Puede usar las API de notificación de fuente de actividad de Microsoft Graph para ampliar esta funcionalidad a las aplicaciones. De este modo, puede proporcionar experiencias más enriquecidas e interactuar con los usuarios ayudándoles a mantenerse al día con los cambios en las herramientas y flujos de trabajo que usan.

Las API de notificación de fuente de actividad de Microsoft Graph habilitan los siguientes casos de uso:

  • Noticias : mantenga a los usuarios actualizados con la información más reciente, como nuevas asignaciones o nuevas publicaciones.
  • Colaboración : muestra a los usuarios una vista previa en el banner de notificación cuando alguien comparte un archivo o @ los menciona en un comentario.
  • Recordatorios : envíe notificaciones a los usuarios sobre eventos o tareas.
  • Alertas : envíe notificaciones que requieran atención urgente o inmediata, como una fecha de vencimiento anterior o un elemento de trabajo de alta prioridad.

Puede usar notificaciones de fuente de actividad para hacer lo siguiente:

  • Notificar a los usuarios sobre el contenido personalizado que requiere su atención.
  • Mostrar contenido enriquecido en una aplicación o dirección URL tab.
  • Admitir interacciones complejas del usuario.
  • Enviar notificaciones delegadas del usuario que inició una notificación.

Teams controla la localización de las notificaciones.

Componentes de las notificaciones de fuente de actividad

Las notificaciones de fuente de actividad en Teams se componen de varios fragmentos de información que se muestran juntos, como se muestra en la siguiente imagen.

Imagen que muestra los componentes de una notificación de fuente de actividad, incluidos actor, motivo, marca de tiempo, vista previa y tema.

En la tabla siguiente se describen los componentes.

Componente Descripción
Avatar Muestra quién inició la actividad.
Tipo de actividad o icono de aplicación Tipo de actividad. En el caso de las notificaciones de aplicación, el icono de línea se reemplaza por un icono de aplicación.
Título: Actor y motivo Actor es el nombre del usuario o la aplicación que inició la actividad. El motivo describe la actividad.
Timestamp Muestra cuándo se produjo la actividad.
Vista previa de texto Muestra una línea truncada desde el inicio de la notificación.
Tema Recurso asociado o el valor de texto del tema desde el cuerpo de la solicitud.

En la imagen siguiente se muestra un ejemplo de una notificación de fuente de actividad en Teams. En este ejemplo, un usuario ha compartido una publicación en una aplicación.

Imagen de una notificación de fuente de actividad de Yammer

Tipos de tarjetas de notificación de fuente de actividad

En las pestañas siguientes se muestran los tipos de tarjetas de notificación de fuente de actividad que puede mostrar. En el caso de las notificaciones generadas por la aplicación, el logotipo de usuario se reemplaza por el logotipo de la aplicación.

Personalizado de Teams

Captura de pantalla que muestra las notificaciones de fuente de actividad en un escritorio personalizado de Teams.

Windows

Captura de pantalla que muestra las notificaciones de fuente de actividad en un equipo de escritorio de Windows Teams.

Mac

Captura de pantalla que muestra las notificaciones de fuente de actividad en un equipo mac desktop Teams.

Requisitos para usar las API de notificación de fuente de actividad

Las API de fuente de actividad funcionan con una aplicación de Teams. Los siguientes son los requisitos para enviar notificaciones de fuente de actividad:

  • El manifiesto de aplicación de Teams debe tener el identificador de la aplicación Microsoft Entra agregado a la webApplicationInfo sección. Para obtener más información, vea esquema de manifiesto.
  • Las notificaciones de actividad se pueden enviar con o sin tipos de actividad declarados en el manifiesto de la aplicación.
    • De forma predeterminada, puede usar las API de notificación de actividad sin declarar la activities sección en el manifiesto. El systemDefault tipo de actividad está reservado, lo que le permite proporcionar texto de forma libre en la Actor+Reason línea de la notificación de fuente de actividad. Para obtener más información, consulte Envío de notificaciones de fuente de actividad personalizables.
    • Si desea enviar una notificación con plantilla en el modo tradicional, los tipos de actividad deben declararse en la sección Actividades . Para obtener más información, vea Esquema de manifiesto.
  • La aplicación de Teams debe estar instalada para el destinatario, ya sea personalmente o en un equipo o chat del que forma parte. Para obtener más información, consulte Instalación de aplicaciones de Teams.

Permissions

Puede usar permisos delegados o de aplicación para enviar notificaciones de actividad. Cuando se usan permisos de aplicación, se recomienda usar el consentimiento específico de recursos (RSC) porque el TeamsActivity.Send.User permiso permite al usuario dar su consentimiento para enviar notificaciones de actividad. Debe declarar permisos de RSC en el esquema de manifiesto de aplicación de Teams.

Actualizaciones del manifiesto de aplicación de Teams

En esta sección se describen los cambios que debe realizar en el manifiesto de aplicación de Teams para implementar las notificaciones de fuente de actividad. Debe usar la versión 1.7 del manifiesto de aplicación de Teams o superior.

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

webApplicationInfo update

Debe actualizar Microsoft Entra id e resource información en la propiedad de manifiesto webApplicationInfo de la aplicación.

"webApplicationInfo":
{
    "id": "a3111f15-658e-457c-9689-fd20fe907330",
    "resource": "https://contosoapp.com"
}
Parámetro Tipo Descripción
id string Microsoft Entra (id. de cliente).
resource string Recurso asociado a la aplicación de Azure AD. También se conoce como URI de respuesta o redirección en la introducción al registro de aplicaciones de Centro de administración Microsoft Entra.

Nota:

Es posible que reciba un error si varias aplicaciones de Teams en el mismo ámbito (equipo, chat o usuario) usan la misma aplicación Microsoft Entra. Asegúrese de que usa aplicaciones Microsoft Entra únicas.

Actualización de actividades

Debe definir la propiedad en el activities manifiesto de la aplicación para publicar una fuente de actividad de usuario.

"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}"
    }
  ]
}
Parámetro Tipo Descripción
tipo string El tipo debe ser único en un manifiesto específico.
description string Descripción breve legible por el usuario. La descripción está visible en el cliente de Microsoft Teams.
templateText string Texto de plantilla para la notificación de actividad. Puede declarar los parámetros encapsulando los parámetros entre corchetes {}.

Nota:

  • actor es un parámetro especial que siempre toma el nombre del autor de la llamada. En las llamadas delegadas, actor es el nombre del usuario. En las llamadas de solo aplicación, toma el nombre de la aplicación de Teams.

  • El tipo de actividad reservada systemDefault no debe proporcionarse en la activities sección del manifiesto. El tipo de actividad reservada puede proporcionar texto de forma libre en la Actor+Reason línea de la notificación de fuente de actividad. Para obtener más información, consulte Envío de notificaciones de fuente de actividad personalizables.

Actualización de autorización

"authorization": 
{ 
  "permissions": { 
    "resourceSpecific": [ 
      {
        "type": "Application", 
         "name": "TeamsActivity.Send.User" 
      }, 
      { 
        "type": "Application",
        "name": "TeamsActivity.Send.Group"
      }, 
      { 
        "type": "Application", 
        "name": "TeamsActivity.Send.Chat" 
      } 
    ] 
  }
}
Parámetro Tipo Descripción
tipo string Tipo de permiso de consentimiento específico del recurso (RSC).
name string Nombre del permiso RSC. Para obtener más información, consulte Permisos de RSC admitidos.

Instalación de la aplicación teams

Las aplicaciones de Teams se pueden instalar en un equipo, un chat o para un usuario personalmente, y se pueden distribuir de varias maneras. Para obtener más información, consulte Métodos de distribución de aplicaciones de Teams. Normalmente, la instalación local se prefiere con fines de desarrollo. Después del desarrollo, puede elegir el método de distribución adecuado en función de si desea distribuir a un inquilino o a todos los inquilinos.

También puede usar las API de instalación de aplicaciones de Teams para administrar las instalaciones de aplicaciones de Teams.

Envío de notificaciones de fuente de actividad a los usuarios

Nota:

Para mostrar notificaciones de fuente de actividad en clientes iOS y Android, la aplicación debe incluirse en la lista de permitidos. Solo se admiten aplicaciones de terceros.

Dado que una aplicación de Teams se puede instalar para un usuario, en un equipo o en un chat, las notificaciones se pueden enviar en tres contextos. Para obtener más información sobre cómo enviar notificaciones en cada contexto, consulte los temas siguientes:

Además, las notificaciones se pueden enviar de forma masiva hasta 100 usuarios a la vez. Para obtener más información, consulte el tema siguiente:

Para obtener más información sobre qué temas se admiten para cada escenario, consulte las API específicas. Los temas personalizados basados en texto se admiten en todos los escenarios.

Nota:

El icono de actividad se basa en el contexto en el que se realiza la solicitud. Si la solicitud se realiza con permisos delegados, la foto del usuario aparece como avatar, mientras que el icono de aplicación de Teams aparece como icono de actividad. En un contexto de solo aplicación, el icono de aplicación de Teams se usa como avatar y se omite el icono de actividad.

Ejemplo 1: Notificar a un usuario sobre una tarea creada en un chat

En el ejemplo siguiente se muestra cómo puede enviar una notificación de fuente de actividad para una nueva tarea creada en un chat. En este caso, la aplicación Teams debe instalarse en un chat con id chatId . y el usuario 569363e2-4e49-4661-87f2-16f245c5d66a también debe formar parte del chat.

Solicitud

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

Respuesta

HTTP/1.1 204 No Content

Ejemplo 2: Notificar a un usuario sobre una tarea creada en un equipo

En el ejemplo siguiente se muestra cómo enviar una notificación de fuente de actividad para un equipo. En este ejemplo se notifica al propietario del equipo sobre una nueva tarea creada que requiere su atención.

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": "taskCreated",
    "previewText": {
        "content": "New Task Created"
    },
    "recipient": {
        "@odata.type": "microsoft.graph.aadUserNotificationRecipient",
        "userId": "569363e2-4e49-4661-87f2-16f245c5d66a"
    },
    "templateParameters": [
        {
            "name": "taskId",
            "value": "12322"
        }
    ]
}

Respuesta

HTTP/1.1 204 No Content

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

Como se muestran en los ejemplos anteriores, puede vincular a diferentes aspectos de equipo o chat. Sin embargo, si desea vincular a un aspecto que no forma parte del equipo o Microsoft Graph no lo representa, o si desea personalizar el nombre, puede establecer el origen del topictext objeto en y pasarle un valor personalizado. Además, webUrl es necesario cuando se usa topic el origen como text.

El ejemplo de notificación de Yammer mostrado anteriormente usa un tema personalizado porque Microsoft Graph no admite los recursos de Yammer.

Nota:

webUrl debe empezar con el dominio de Microsoft Teams (teams.microsoft.com, por ejemplo).

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

Respuesta

HTTP/1.1 204 No Content

Ejemplo 4: Notificar a los miembros del equipo sobre un evento

En el ejemplo siguiente se muestra cómo enviar una notificación de fuente de actividad a todos los miembros del equipo. En este ejemplo se notifica a los miembros del equipo sobre un nuevo evento.

Solicitud

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

Respuesta

HTTP/1.1 204 No Content

Ejemplo 5: Notificar a los miembros del canal sobre un evento

En el ejemplo siguiente se muestra cómo enviar una notificación de fuente de actividad a todos los miembros del canal. En este ejemplo se notifica a los miembros del canal sobre un nuevo evento.

Solicitud

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

Respuesta

HTTP/1.1 204 No Content

Ejemplo 6: Notificar a los miembros del chat sobre un evento

En el ejemplo siguiente se muestra cómo puede enviar una notificación de fuente de actividad a todos los miembros del chat. En este ejemplo se notifica a los miembros del chat sobre un nuevo evento.

Solicitud

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

Respuesta

HTTP/1.1 204 No Content

Ejemplo 7: Notificar a varios usuarios sobre solicitudes de aprobación financiera pendientes

En el ejemplo siguiente se muestra cómo enviar una notificación de fuente de actividad a varios usuarios de forma masiva. En este ejemplo se notifica a varias partes interesadas sobre las solicitudes de aprobación financiera pendientes.

Solicitud

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

Respuesta

HTTP/1.1 202 Accepted

Ejemplo 8: Envío de una notificación a un usuario mediante el tipo de actividad systemDefault

En el ejemplo siguiente se muestra cómo enviar una notificación de actividad para un equipo sin tipos de actividad definidos en el manifiesto. Tiene la flexibilidad de proporcionar texto de forma libre aquí. Para obtener más información, vea Tipos de actividad reservadas.

En este ejemplo se notifica al propietario del equipo que tome un breve descanso. Modifique el value elemento en templateParameters para personalizar la notificación para varios escenarios.

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

Respuesta

HTTP/1.1 204 No Content

Tipos de actividad reservada

El systemDefault tipo de actividad está reservado y no se puede usar en el manifiesto al declarar Actividades. Puede usar el tipo de systemDefault actividad para:

  • Pruebe fácilmente nuevos escenarios o pruebe rápidamente las API de notificación de fuente de actividad sin definir los tipos de actividad en el manifiesto de la aplicación.
  • En el caso de las aplicaciones de la Tienda, ahorre tiempo y optimice el proceso, ya que no es necesario ajustar constantemente los tipos de actividad en el manifiesto de la aplicación. El systemDefault tipo de actividad está listo para usarse desde el get-go.

Tenga en cuenta que, con el systemDefault tipo de actividad, no puede:

  • Use las características de localización integradas proporcionadas por los manifiestos.
  • Confíe en el envío de notificaciones personalizables con el tipo de systemDefault actividad. Los usuarios pueden desactivar todas las notificaciones de la aplicación con un botón de alternancia en la configuración de cliente de Microsoft Teams, lo que puede dificultar la comunicación entre la aplicación y sus usuarios.

Todavía se recomiendan las notificaciones con plantilla para lotes periódicos y grandes de notificaciones, ya que requieren plantillas de actividad en el manifiesto.

El systemDefault tipo de actividad reservada permanece disponible, independientemente de los tipos de actividad enumerados en el manifiesto de la aplicación.

Personalización de la forma en que las notificaciones le alertan

Los usuarios de Microsoft Teams pueden personalizar las notificaciones que ven en su fuente, como un banner, etc. Las notificaciones generadas a través de las API de fuente de actividad también se pueden personalizar. Los usuarios pueden elegir cómo se les notifica a través de la configuración de Microsoft Teams. Las aplicaciones de Teams aparecen en la lista para que el usuario elija, como se muestra en la captura de pantalla siguiente.

Captura de pantalla de la configuración de notificaciones en Teams, con la opción Personalizada resaltada

Los usuarios pueden elegir Editar junto a una aplicación y personalizar las notificaciones, como se muestra en el ejemplo siguiente. Se description muestra el campo del manifiesto de aplicación de Teams.

Captura de pantalla que muestra las notificaciones personalizadas en Banner y fuente para una aplicación de Teams

Preguntas frecuentes

¿Quién necesita instalar la aplicación de Teams?

El usuario de destino debe tener instalada la aplicación de Teams que envía notificaciones.

¿Puede un usuario enviar notificaciones a sí mismo?

No, un usuario no puede enviar notificaciones a sí mismo. Para este escenario, use permisos de aplicación.

¿Puede una aplicación de Teams controlar cómo se muestran las notificaciones al usuario?

No, solo los usuarios pueden cambiar la configuración de notificación.

He instalado mi aplicación; ¿por qué no veo la configuración de notificación en la cuenta de usuario?

La configuración aparece después de que la aplicación teams envíe la primera notificación. Esto reduce el número de configuraciones que ven los usuarios.

Comencé a obtener un error 409 (conflicto); ¿cómo puedo resolverlo?

ConflictLos errores se producen principalmente cuando varias aplicaciones de Teams instaladas en el mismo ámbito (equipo, chat, usuario, etc.) tienen el mismo Microsoft Entra appId en la webApplicationInfo sección del manifiesto. Cuando esto sucede, se produce un error como Found multiple applications with the same Microsoft Entra App ID 'Your Microsoft Entra AppId'.. Asegúrese de usar aplicaciones Microsoft Entra únicas para aplicaciones únicas de Teams. Puede instalar la misma aplicación de Teams en varios ámbitos (equipo y usuario, por ejemplo).

Contenido relacionado