Commentaires Modifier

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

  • Article
  • 9 minutes de lecture

Le flux d’activités Microsoft Teams permet aux utilisateurs de trier les éléments qui nécessitent une attention particulière en les notifiant des modifications. Vous pouvez utiliser les API de notification de flux d’activité dans Microsoft Graph pour étendre cette fonctionnalité à vos applications. Cela permet à vos applications de fournir des expériences plus riches et de mieux impliquer les utilisateurs en les aidant à rester à jour avec les modifications apportées aux outils et aux flux de travail qu’ils utilisent.

Comprendre les principes de base de la notification de flux d’activité

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

Image montrant les composants d’une notification de flux d’activité

Les composants sont les suivants :

  • L’acteur qui a initié l’activité
  • Icône représentant le type d’activité
  • La raison pour laquelle l’acteur a eu l’activité
  • Aperçu de texte
  • Date et heure
  • Emplacement de l’activité

L’exemple suivant montre comment ces composants fournissent ensemble les détails d’une notification. Cet exemple est une notification concernant un utilisateur mentionné dans une communauté Yammer.

Exemple de notification d’actifity Yammer

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é :

  • L’ID d’application Azure AD doit être ajouté au manifeste de l’application webApplicationInfo Teams. Pour plus d’informations, consultez le schéma de manifeste.
  • Les types d’activités doivent être déclarés dans la activities section. Pour plus d’informations, consultez le 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 l’installation de l’application Teams.

Modifications du manifeste de l’application Teams

Cette section décrit les modifications qui doivent être ajoutées au manifeste de l’application Teams. Notez que 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",

Modifications apportées à la section webApplicationInfo

"webApplicationInfo":
{
    "id": "a3111f15-658e-457c-9689-fd20fe907330",
    "resource": "https://contosoapp.com"
}
Paramètre Type Description
id chaîne ID d’application Azure AD (ID client).
ressource chaîne Ressource associée à l’application Azure AD. Également appelée URL de réponse ou de redirection dans le portail Azure.

Notes

Vous pouvez obtenir une erreur si plusieurs applications Teams dans la même étendue (équipe, conversation ou utilisateur) utilisent la même application Azure AD. Assurez-vous que vous utilisez des applications Azure AD uniques.

modifications apportées à la section activités

"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 Type d’activité. Cela doit être unique dans un manifeste spécifique.
description string Description courte lisible par l’homme. Celui-ci sera 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 dans {}.

Notes

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

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 les 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

Étant donné qu’une application Teams peut être installée pour un utilisateur, dans une équipe ou dans une conversation, les notifications peuvent également être envoyées dans les trois contextes suivants :

En outre, les notifications peuvent être envoyées en bloc jusqu’à 100 utilisateurs à la fois :

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.

Notes

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

Cet exemple 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 ID chatId et l’utilisateur 569363e2-4e49-4661-87f2-16f245c5d66a doit également faire partie de la conversation.

Demande

POST https://graph.microsoft.com/beta/chats/{chatId}/sendActivityNotification
Content-Type: application/json

{
    "topic": {
        "source": "entityUrl",
        "value": "https://graph.microsoft.com/beta/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

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

Demande

POST https://graph.microsoft.com/beta/teams/{teamId}/sendActivityNotification
Content-Type: application/json

{
    "topic": {
        "source": "entityUrl",
        "value": "https://graph.microsoft.com/beta/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 : informer un utilisateur d’un événement à l’aide d’une rubrique personnalisée

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

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

Notes

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

Demande

POST https://graph.microsoft.com/beta/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

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

Notes

La possibilité d’envoyer des notifications à tous les membres de l’équipe est actuellement disponible uniquement en version bêta.

Demande

POST https://graph.microsoft.com/beta/teams/7155e3c8-175e-4311-97ef-572edc3aa3db/sendActivityNotification
Content-Type: application/json

{
    "topic": {
        "source": "text",
        "value": "Weekly Virtual Social",
        "webUrl": "Teams webUrl"
    },
    "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

Cet exemple 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.

Notes

La possibilité d’envoyer des notifications à tous les membres du canal est actuellement disponible uniquement en version bêta.

Demande

POST https://graph.microsoft.com/beta/teams/7155e3c8-175e-4311-97ef-572edc3aa3db/sendActivityNotification
Content-Type: application/json

{
    "topic": {
        "source": "text",
        "value": "Weekly Virtual Social",
        "webUrl": "Teams webUrl"
    },
    "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

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

Notes

La possibilité d’envoyer des notifications à tous les membres de la conversation est actuellement disponible uniquement en version bêta.

Demande

POST https://graph.microsoft.com/beta/chats/19:d65713bc498c4a428c71ef9353e6ce20@thread.v2/sendActivityNotification
Content-Type: application/json

{
    "topic": {
        "source": "text",
        "value": "Weekly Virtual Social",
        "webUrl": "Teams webUrl"
    },
    "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ères 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ères en attente.

Notes

La possibilité d’envoyer des notifications à plusieurs utilisateurs en bloc est actuellement disponible uniquement en version bêta.

Demande

POST https://graph.microsoft.com/beta/teamwork/sendActivityNotificationToRecipients
Content-Type: application/json

{
    "topic": {
        "source": "entityUrl",
        "value": "https://graph.microsoft.com/beta/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

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, et ainsi de suite. Les notifications générées par le biais des API de flux d’activité peuvent également être personnalisées. Les utilisateurs peuvent choisir la façon dont ils sont avertis via des paramètres dans Microsoft Teams. Les applications Teams s’affichent dans la liste de choix de l’utilisateur, comme illustré dans la capture d’écran suivante.

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

Les utilisateurs peuvent cliquer sur 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 les notifications personnalisées en bannière et flux pour une application Teams

FAQ

Qui doit installer l’application Teams ?

L’application Teams qui envoie des notifications doit être installée pour l’utilisateur cible.

Un utilisateur peut-il envoyer des notifications à lui-même ?

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 ne vois-je pas les paramètres de notification sous le compte d’utilisateur ?

Les paramètres s’affichent après l’envoi de la première notification par l’application Teams. Cela réduit le nombre de paramètres que les utilisateurs voient.

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

Conflict Les erreurs se produisent principalement lorsque plusieurs applications Teams installées dans la même étendue (équipe, conversation, utilisateur, et ainsi de suite) ont le même ID d’application Azure AD dans la webApplicationInfo section du manifeste. Dans ce cas, vous obtiendrez une erreur telle que Found multiple applications with the same Azure AD App ID 'Your AzureAD AppId'.. Veillez à utiliser des applications Azure AD uniques pour des applications Teams uniques. Notez que la même application Teams peut être installée dans plusieurs étendues (équipe + utilisateur, par exemple).

Voir aussi