Envoyer des notifications de flux d’activité aux utilisateurs dans Microsoft Teams

  • Article

Le flux d’activité Microsoft Teams avertit les utilisateurs des modifications pour leur permettre de trier les éléments qui nécessitent une attention particulière. Les notifications de flux d’activité dans Teams incluent les fonctionnalités suivantes :

  • Intégration native à Teams qui amène l’utilisateur en toute transparence dans l’application Onglet et fournit un engagement utilisateur supplémentaire à partir du volet Activité Teams à votre application.
  • Notifications de système d’exploitation dans les clients de bureau et mobiles Teams qui incluent une fenêtre contextuelle et un son.
  • Contenu de notification personnalisable qui vous permet d’afficher plus ou moins de contenu d’aperçu à l’utilisateur.
  • Possibilité de lier en profondeur votre onglet, votre application personnelle, votre message de bot ou votre carte adaptative à une notification pour augmenter l’engagement des utilisateurs avec votre application.
  • Possibilité d’envoyer des notifications de flux d’activité à plusieurs destinataires, telles que des notifications par lots à un groupe d’utilisateurs.

Vous pouvez utiliser les API de notification de flux d’activité dans Microsoft Graph pour étendre cette fonctionnalité à vos applications. De cette façon, vous pouvez fournir des expériences plus riches et impliquer les utilisateurs en les aidant à rester à jour avec les modifications apportées aux outils et aux flux de travail qu’ils utilisent.

Les API de notification de flux d’activité dans Microsoft Graph permettent les cas d’usage suivants :

  • Actualités : tenez les utilisateurs à jour avec les informations les plus récentes, telles que de nouvelles affectations ou de nouveaux billets.
  • Collaboration : affichez aux utilisateurs un aperçu dans la bannière de notification lorsqu’une personne partage un fichier ou @ les mentionne dans un commentaire.
  • Rappels : envoyer des notifications aux utilisateurs sur des événements ou des tâches.
  • Alertes : envoyez des notifications qui nécessitent une attention urgente ou immédiate, comme une date d’échéance passée ou un élément de travail de priorité élevée.

Vous pouvez utiliser les notifications de flux d’activité pour effectuer les opérations suivantes :

  • Informez les individus du contenu personnalisé qui nécessite leur attention.
  • Afficher du contenu enrichi dans une application Tab ou une URL.
  • Prendre en charge les interactions utilisateur complexes.
  • Envoyer des notifications déléguées de l’utilisateur qui a lancé une notification.

Teams gère la localisation des notifications.

Composants des notifications de flux d’activité

Les notifications de flux d’activité dans Teams sont composées de plusieurs informations affichées ensemble, comme illustré dans l’image suivante.

Image montrant les composants d’une notification de flux d’activité, notamment l’acteur, la raison, l’horodatage, l’aperçu et la rubrique.

Le tableau suivant décrit les composants.

Composant Description
Avatar Indique qui a initié l’activité.
Type d’activité ou icône d’application Type d’activité. Pour les notifications d’application, l’icône de ligne est remplacée par une icône d’application.
Titre : Acteur + raison Actor est le nom de l’utilisateur ou de l’application qui a lancé l’activité. La raison décrit l’activité.
Timestamp Indique quand l’activité s’est produite.
Aperçu du texte Affiche une ligne tronquée à partir du début de la notification.
Rubrique Ressource associée ou valeur de texte de la rubrique à partir du corps de la demande.

L’image suivante montre un exemple de notification de flux d’activité dans Teams. Dans cet exemple, un utilisateur a partagé une publication dans une application.

Image d’une notification de flux d’activité Yammer

Types de cartes de notification de flux d’activité

Les onglets suivants affichent les types de cartes de notification de flux d’activité que vous pouvez afficher. Pour les notifications générées par l’application, le logo utilisateur est remplacé par le logo de l’application.

Teams personnalisé

Capture d’écran montrant les notifications de flux d’activité dans un bureau teams personnalisé.

Fenêtres

Capture d’écran montrant les notifications de flux d’activité dans un bureau Windows Teams.

Mac

Capture d’écran montrant les notifications de flux d’activité dans un ordinateur de bureau Mac Teams.

Configuration requise pour l’utilisation des API de notification de flux d’activité

Les API de flux d’activité fonctionnent avec une application Teams. Voici les conditions requises pour l’envoi de notifications de flux d’activité :

  • Le manifeste de l’application Teams doit avoir l’ID d’application Microsoft Entra ajouté à la webApplicationInfo section. Pour plus d’informations, consultez Schéma de manifeste.
  • Les notifications d’activité peuvent être envoyées avec ou sans types d’activité déclarés dans le manifeste de l’application.
    • Par défaut, vous pouvez utiliser les API de notification d’activité sans déclarer la activities section dans le manifeste. Le systemDefault type d’activité est réservé, ce qui vous permet de fournir du texte de forme libre dans la Actor+Reason ligne de la notification de flux d’activité. Pour plus d’informations, consultez Envoyer des notifications de flux d’activité personnalisables.

      Remarque

      Le systemDefault type d’activité est disponible uniquement en préversion publique.

    • Si vous souhaitez envoyer une notification basée sur un modèle en mode traditionnel, les types d’activité doivent être déclarés dans la section Activités . Pour plus d’informations, consultez Schéma de manifeste.
  • L’application Teams doit être installée pour le destinataire, soit personnellement, soit dans une équipe ou une conversation dont il fait partie. Pour plus d’informations, consultez Installation d’applications Teams.

Autorisations

Vous pouvez utiliser des autorisations déléguées ou d’application pour envoyer des notifications d’activité. Lorsque vous utilisez des autorisations d’application, nous vous recommandons d’utiliser le consentement spécifique à la ressource (RSC), car l’autorisation TeamsActivity.Send.User permet à l’utilisateur de donner son consentement pour envoyer des notifications d’activité. Vous devez déclarer des autorisations RSC dans votre schéma de manifeste d’application Teams.

Mises à jour du manifeste de l’application Teams

Cette section décrit les modifications que vous devez apporter au manifeste de l’application Teams pour implémenter les notifications de flux d’activité. Vous devez utiliser la version du manifeste de l’application Teams ou une version 1.7 ultérieure.

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

Mise à jour webApplicationInfo

Vous devez mettre à jour Microsoft Entra id et resource les informations dans la propriété de manifeste webApplicationInfo de votre application.

"webApplicationInfo":
{
    "id": "a3111f15-658e-457c-9689-fd20fe907330",
    "resource": "https://contosoapp.com"
}
Paramètre Type Description
id string Microsoft Entra (ID client).
ressource string Ressource associée à l’application Azure AD. Il est également appelé URI de réponse ou de redirection dans la vue d’ensemble de l’inscription de l’application centre d'administration Microsoft Entra.

Remarque

Vous pouvez obtenir une erreur si plusieurs applications Teams dans la même étendue (équipe, conversation ou utilisateur) utilisent la même application Microsoft Entra. Vérifiez que vous utilisez des applications Microsoft Entra uniques.

Mise à jour des activités

Vous devez définir la propriété dans le activities manifeste de votre application pour publier un flux d’activité utilisateur.

"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}"
    }
  ]
}
Paramètre Type Description
type string Le type doit être unique dans un manifeste spécifique.
description string Brève description lisible par l’utilisateur. La description est visible sur le client Microsoft Teams.
templateText string Texte du modèle pour la notification d’activité. Vous pouvez déclarer vos paramètres en encapsulant les paramètres entre accolades {}.

Remarque

  • actor est un paramètre spécial qui prend toujours le nom de l’appelant. Dans les appels délégués, actor est le nom de l’utilisateur. Dans les appels d’application uniquement, il prend le nom de l’application Teams.

  • Le type d’activité réservée systemDefault ne doit pas être fourni dans la activities section du manifeste. Le type d’activité réservée peut fournir du texte de forme libre dans la Actor+Reason ligne de la notification de flux d’activité. Pour plus d’informations, consultez Envoyer des notifications de flux d’activité personnalisables.

Mise à jour des autorisations

"authorization": 
{ 
  "permissions": { 
    "resourceSpecific": [ 
      {
        "type": "Application", 
         "name": "TeamsActivity.Send.User" 
      }, 
      { 
        "type": "Application",
        "name": "TeamsActivity.Send.Group"
      }, 
      { 
        "type": "Application", 
        "name": "TeamsActivity.Send.Chat" 
      } 
    ] 
  }
}
Paramètre Type Description
type string Type d’autorisation de consentement spécifique à la ressource (RSC).
nom string Nom de l’autorisation RSC. Pour plus d’informations, consultez Autorisations RSC prises en charge

Installer l’application Teams

Les applications Teams peuvent être installées dans une équipe, une conversation ou pour un utilisateur personnellement, et peuvent être distribuées de plusieurs façons. Pour plus d’informations, consultez Méthodes de distribution d’applications Teams. En règle générale, le chargement indépendant est préférable à des fins de développement. Après le développement, vous pouvez choisir la méthode de distribution appropriée selon que vous souhaitez distribuer à un locataire ou à tous les locataires.

Vous pouvez également utiliser les API d’installation d’applications Teams pour gérer les installations d’applications Teams.

Envoyer des notifications de flux d’activité aux utilisateurs

Remarque

Pour afficher les notifications de flux d’activité sur les clients iOS et Android, l’application doit être incluse dans la liste verte. Seules les applications tierces sont prises en charge.

Étant donné qu’une application Teams peut être installée pour un utilisateur, dans une équipe ou dans une conversation, les notifications peuvent être envoyées dans trois contextes. Pour plus d’informations sur l’envoi de notifications dans chaque contexte, consultez les rubriques suivantes :

En outre, les notifications peuvent être envoyées en bloc à jusqu’à 100 utilisateurs à la fois. Pour plus d’informations, consultez la rubrique suivante :

Pour plus d’informations sur les rubriques prises en charge pour chaque scénario, consultez les API spécifiques. Les rubriques textuelles personnalisées sont prises en charge pour tous les scénarios.

Remarque

L’icône d’activité est basée sur le contexte dans lequel la demande est effectuée. Si la demande est effectuée avec des autorisations déléguées, la photo de l’utilisateur apparaît en tant qu’avatar, tandis que l’icône de l’application Teams apparaît en tant qu’icône d’activité. Dans un contexte d’application uniquement, l’icône d’application Teams est utilisée comme avatar, et l’icône d’activité est omise.

Exemple 1 : Informer un utilisateur d’une tâche créée dans une conversation

L’exemple suivant montre comment envoyer une notification de flux d’activité pour une nouvelle tâche créée dans une conversation. Dans ce cas, l’application Teams doit être installée dans une conversation avec l’ID chatId et l’utilisateur 569363e2-4e49-4661-87f2-16f245c5d66a doit également faire partie de la conversation.

Demande

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

Réponse

HTTP/1.1 204 No Content

Exemple 2 : Informer un utilisateur d’une tâche créée dans une équipe

L’exemple suivant montre comment envoyer une notification de flux d’activité pour une équipe. Cet exemple avertit le propriétaire de l’équipe d’une nouvelle tâche créée qui nécessite son attention.

Demande

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

Réponse

HTTP/1.1 204 No Content

Exemple 3 : Avertir un utilisateur d’un événement à l’aide d’une rubrique personnalisée

Comme le montrent les exemples précédents, vous pouvez créer un lien vers différents aspects d’équipe ou de conversation. Toutefois, si vous souhaitez créer un lien vers un aspect qui ne fait pas partie de l’équipe ou si Microsoft Graph ne le représente pas, ou si vous souhaitez personnaliser le nom, vous pouvez définir la source du topic sur text et lui transmettre une valeur personnalisée. En outre, webUrl est obligatoire lorsque vous utilisez topic source en tant que text.

L’exemple de notification Yammer présenté précédemment utilise une rubrique personnalisée, car Microsoft Graph ne prend pas en charge les ressources de Yammer.

Remarque

webUrl doit commencer par le domaine Microsoft Teams (teams.microsoft.com, par exemple).

Demande

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

Réponse

HTTP/1.1 204 No Content

Exemple 4 : Informer les membres de l’équipe d’un événement

L’exemple suivant montre comment envoyer une notification de flux d’activité à tous les membres de l’équipe. Cet exemple avertit les membres de l’équipe d’un nouvel événement.

Demande

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

Réponse

HTTP/1.1 204 No Content

Exemple 5 : Informer les membres du canal d’un événement

L’exemple suivant montre comment envoyer une notification de flux d’activité à tous les membres du canal. Cet exemple avertit les membres du canal d’un nouvel événement.

Demande

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

Réponse

HTTP/1.1 204 No Content

Exemple 6 : Informer les membres de la conversation d’un événement

L’exemple suivant montre comment envoyer une notification de flux d’activité à tous les membres de la conversation. Cet exemple avertit les membres de la conversation d’un nouvel événement.

Demande

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

Réponse

HTTP/1.1 204 No Content

Exemple 7 : Informer plusieurs utilisateurs des demandes d’approbation financière en attente

L’exemple suivant montre comment envoyer une notification de flux d’activité à plusieurs utilisateurs en bloc. Cet exemple informe plusieurs parties prenantes des demandes d’approbation financière en attente.

Demande

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

Réponse

HTTP/1.1 202 Accepted

Exemple 8 : Envoyer une notification à un utilisateur à l’aide du type d’activité systemDefault

L’exemple suivant montre comment envoyer une notification d’activité pour une équipe sans type d’activité défini dans le manifeste. Vous avez la possibilité de fournir du texte libre ici. Pour plus d’informations, consultez Types d’activité réservés.

Remarque

Le systemDefault type d’activité est disponible uniquement en préversion publique.

Cet exemple montre comment avertir le propriétaire de l’équipe de prendre une courte pause. Modifiez le value dans templateParameters pour personnaliser la notification pour différents scénarios.

Demande

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

Réponse

HTTP/1.1 204 No Content

Types d’activités réservées

Le systemDefault type d’activité est réservé et ne peut pas être utilisé dans le manifeste lors de la déclaration d’activités. Vous pouvez utiliser le type d’activité systemDefault pour :

  • Testez facilement de nouveaux scénarios et/ou essayez rapidement les API de notification de flux d’activité sans définir de types d’activité dans le manifeste de votre application.
  • Pour les applications du Windows Store, gagnez du temps et simplifiez le processus, car vous n’avez pas besoin d’ajuster constamment les types d’activité dans le manifeste de votre application. Le systemDefault type d’activité est prêt à être utilisé dès le départ.

Gardez à l’esprit qu’avec le systemDefault type d’activité, vous ne pouvez pas :

  • Utilisez les fonctionnalités de localisation intégrées fournies par les manifestes.
  • Reposez-vous sur l’envoi de notifications personnalisables avec le type d’activité systemDefault . Les utilisateurs peuvent désactiver toutes les notifications de votre application avec un bouton bascule dans les paramètres du client Microsoft Teams, ce qui peut nuire à la communication entre votre application et ses utilisateurs.

Nous recommandons toujours les notifications avec modèle pour les lots récurrents et volumineux de notifications, car elles nécessitent des modèles d’activité dans le manifeste.

Le systemDefault type d’activité réservée reste disponible, quels que soient les types d’activité répertoriés dans le manifeste de votre application.

Personnaliser la façon dont les notifications vous alertent

Les utilisateurs de Microsoft Teams peuvent personnaliser les notifications qu’ils voient dans leur flux, sous la forme d’une bannière, etc. Les notifications générées via les API de flux d’activité peuvent également être personnalisées. Les utilisateurs peuvent choisir la façon dont ils sont avertis via les paramètres dans Microsoft Teams. Les applications Teams s’affichent dans la liste pour l’utilisateur, comme illustré dans la capture d’écran suivante.

Capture d’écran des paramètres notifications dans Teams, avec l’option Personnalisé mise en évidence

Les utilisateurs peuvent choisir Modifier en regard d’une application et personnaliser les notifications, comme illustré dans l’exemple suivant. Le description champ dans le manifeste de l’application Teams s’affiche.

Capture d’écran montrant des notifications personnalisées pour une bannière et un flux pour une application Teams

FAQ

Qui doit installer l’application Teams ?

L’utilisateur cible doit avoir installé l’application Teams qui envoie des notifications.

Un utilisateur peut-il s’envoyer des notifications ?

Non, un utilisateur ne peut pas s’envoyer de notifications. Pour ce scénario, utilisez les autorisations d’application.

Une application Teams peut-elle contrôler la façon dont les notifications sont affichées à l’utilisateur ?

Non, seuls les utilisateurs sont autorisés à modifier les paramètres de notification.

J’ai installé mon application ; Pourquoi les paramètres de notification ne s’affichent-ils pas sous le compte d’utilisateur ?

Les paramètres s’affichent une fois que l’application Teams a envoyé la première notification. Cela réduit le nombre de paramètres que les utilisateurs voient.

J’ai commencé à obtenir une erreur 409 (conflit) ; comment le résoudre ?

Conflictles erreurs se produisent principalement lorsque plusieurs applications Teams installées dans la même étendue (équipe, conversation, utilisateur, etc.) ont le même Microsoft Entra appId dans la webApplicationInfo section du manifeste. Lorsque cela se produit, vous obtenez une erreur telle que Found multiple applications with the same Microsoft Entra App ID 'Your Microsoft Entra AppId'.. Veillez à utiliser des applications Microsoft Entra uniques pour les applications Teams uniques. Vous pouvez installer la même application Teams dans plusieurs étendues (équipe + utilisateur, par exemple).

Contenu connexe