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

Le flux Microsoft Teams d’activité 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és 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’elles utilisent.

Comprendre les principes de base des notifications de flux d’activités

Les notifications de flux d 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és

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 Yammer communauté.

Yammer de notification d’actifité

Conditions requises pour l’utilisation des API de notification de flux d’activités

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

Teams de manifeste d’application

Cette section décrit les modifications qui doivent être ajoutées au Teams manifeste de l’application. Notez que vous devez utiliser la version Teams manifeste de l’application ou une version 1.7 supé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 string ID d’application Azure AD (ID client).
ressource string Ressource associée à l’application Azure AD. Également appelée URL de réponse ou de redirection dans le portail Azure.

Remarque : 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 de section d’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é. Il doit être unique dans un manifeste spécifique.
description string Description courte lisible par l’homme. Cela sera visible sur le client Microsoft Teams client.
templateText string Modèle de texte pour la notification d’activité. Vous pouvez déclarer vos paramètres en encapsulant les paramètres dans {} .

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’Teams application.

Installation de l’Teams’application

Teams applications peuvent être installées dans une équipe, une conversation ou pour un utilisateur personnel, et peuvent être distribuées de plusieurs manières. Pour plus d’informations, voir Teams de distribution d’application. En règle générale, le chargement de version secondaire est préférable à des fins de développement. Après le développement, vous pouvez choisir la bonne méthode de distribution selon que vous souhaitez distribuer à un seul client ou à tous les locataires.

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

Envoi de notifications de flux d’activités 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 ci-après :

Pour plus d’informations sur les rubriques qui sont pris en charge pour chaque scénario, voir les API spécifiques. Les rubriques texte personnalisées sont pris en charge pour tous les scénarios.

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

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és pour une nouvelle tâche créée dans une conversation. Dans ce cas, l’Teams doit être installée dans une conversation avec ID et l’utilisateur doit également faire partie de chatId 569363e2-4e49-4661-87f2-16f245c5d66a 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és pour une équipe. Cet exemple avertit le propriétaire de l’équipe sur une nouvelle tâche créée qui nécessite leur 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 le montrent les exemples précédents, vous pouvez établir des liens 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 n’est pas représenté par Microsoft Graph, ou si vous souhaitez personnaliser le nom, vous pouvez définir la source de l’élément et lui transmettre une valeur topic text personnalisée. En outre, webUrl est requis lorsque vous utilisez la source en tant que topic text .

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

Remarque : 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és à tous les membres de l’équipe. Cet exemple informe les membres de l’équipe d’un nouvel événement.

Remarque : 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és à tous les membres du canal. Cet exemple informe les membres du canal d’un nouvel événement.

Remarque : 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és à tous les membres de la conversation. Cet exemple informe les membres de la conversation d’un nouvel événement.

Remarque : La possibilité d’envoyer des notifications à tous les membres de 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

Personnalisation de la façon dont les notifications vous alertent

Microsoft Teams utilisateurs peuvent personnaliser les notifications qu’ils voient dans leur flux, en tant que bannière, etc. Les notifications générées par le biais des API de flux d’activités peuvent également être personnalisées. Les utilisateurs peuvent choisir la façon dont ils sont avertis via les paramètres Microsoft Teams. Teams applications 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 à côté d’une application et personnaliser les notifications, comme illustré dans l’exemple suivant. Le description champ du manifeste Teams’application s’affiche.

Capture d’écran montrant les notifications personnalisées sur Bannière et flux pour une Teams application

FAQ

Qui’installer l’application Teams?.

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

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

Non, un utilisateur ne peut pas envoyer de notifications à lui-même. 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 Teams appl. Cela réduit le nombre de paramètres que les utilisateurs voient.

J’ai commencé à recevoir une erreur 409 (conflit), comment puis-je la 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 appId Azure AD dans la section du webApplicationInfo manifeste. Lorsque cela se produit, vous obtenez 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 les applications Teams uniques. Notez que vous pouvez avoir la même Teams’application installée dans plusieurs étendues (équipe + utilisateur, par exemple).

Voir aussi

Meilleures pratiques pour l’utilisation Microsoft Teams notifications de flux d’activités.