Messagerie proactive utilisant un bot dans Microsoft teamsProactive messaging using a bot in Microsoft Teams

Un message proactif est un message envoyé à un utilisateur de Microsoft teams sans qu’aucun utilisateur n’entame la conversation.A proactive message is a message sent to a Microsoft Teams user without a user initiating the conversation. Les applications personnalisées de Microsoft teams peuvent envoyer des messages proactifs aux utilisateurs à l’aide d’un bot.Custom apps in Microsoft Teams can send proactive messages to users using a bot. Toutefois, pour ce faire, le bot doit être installé en tant qu’application personnelle ou dans une équipe dont l’utilisateur est membre.However, to do so, the bot needs to be installed either as a personal app, or in a team that the user is a member of. Cette exigence peut être prohibitif dans les cas où vous devez afficher de manière proactive un message pour un groupe d’utilisateurs dont l’application teams est ou non installée.This requirement can be prohibitive in scenarios where you need to proactively message a group of users that might or might not have the Teams app installed.

Cet article explique comment vous pouvez combiner Microsoft Graph avec une application Microsoft teams pour installer l’application pour vos utilisateurs, puis utiliser votre application teams pour leur envoyer un message proactif, sans avoir à installer manuellement l’application.This article outlines how you can combine Microsoft Graph with a Microsoft Teams app to install the app for your users and then use your Teams app to send them a proactive message, without requiring them to manually install the app.

À un niveau élevé, vous devez :At a high level, you'll need to:

Création de votre application teams et de votre botCreate your Teams app and bot

Si vous n’avez pas déjà une application Microsoft teams avec un bot qui peut envoyer le message, vous devez en créer une.If you do not already have a Microsoft Teams app with a bot that can send the message, you'll need to create one. Voir Ajouter des robots aux applications teams dans la documentation de la plateforme Teams.See Add bots to Teams apps in the Teams platform documentation. Pour plus d’informations sur la création d’un bot pour la messagerie proactive, consultez la rubrique proactive Messaging for bots.For specifics about creating a bot for proactive messaging, see Proactive messaging for bots.

Vous pouvez également utiliser le modèle d’application Communicator de l’entreprise comme point de départ pour votre application.You can also use the Company Communicator app template as a good starting point for your app. Ce modèle d’application est une application Microsoft teams prête pour la production capable de créer, de planifier et de distribuer des messages à l’échelle de l’entreprise.This app template is a production-ready Microsoft Teams app capable of creating, scheduling, and distributing company-wide messages.

Lors de la création de votre application, assurez-vous de prendre note des remarques que id vous utilisez dans votre manifeste d’application ; vous en aurez besoin pour installer l’application dans une étape ultérieure.When creating your app, make sure that you take note of the id you use in your application manifest; you'll need it to install the app in a subsequent step.

Si vous effectuez cette opération pour une grande organisation, les messages de bienvenue de votre robot peuvent être limités.If you're doing this for a large organization, the welcome messages from your bot might get throttled. Dans la mesure du possible, effectuez les installations par lots et implémentez la fonctionnalité de back-out dans votre bot.If possible, perform the installations in batches, and implement back-off functionality in your bot. Pour plus d’informations, consultez la rubrique gestion de la limitation.For details, see handling rate limiting.

Déployer votre application sur votre catalogue d’applications clientDeploy your app to your tenant app catalog

Microsoft Graph peut uniquement installer des applications qui ont été ajoutées à votre catalogue d’applications client ou qui sont disponibles dans le magasin d’applications Microsoft teams public.Microsoft Graph can only install apps that have been added to your tenant app catalog, or are available in the public Microsoft Teams app store. Si vous utilisez une nouvelle application, vous devez vous assurer qu’il s’agit du catalogue d’applications client.If you're working with a new app, you'll need to make sure it is tenant app catalog.

Installer l’application pour vos utilisateursInstall the app for your users

Pour installer l’application teams pour vos utilisateurs, vous devez d’abord vous assurer que votre application Microsoft Graph dispose des autorisations appropriées : User. ReadWrite. All ou Directory. ReadWrite. All pour installer l’application Teams.To install the Teams app for your users, you'll first need to ensure that your Microsoft Graph application has the right permissions – you'll need User.ReadWrite.All or Directory.ReadWrite.All to install the Teams app. Vous aurez également besoin de conversation. Read. All pour une étape ultérieure.You'll also need Chat.Read.All for a subsequent step. Les deux autorisations nécessitent un consentement de l’administrateur et vous devez utiliser des autorisations d’application plutôt que des délégués utilisateur, car vous installerez des applications pour des utilisateurs autres que vous-même.Both permissions will require admin consent, and you'll need to use application permissions rather than user delegated because you will be installing apps to users other than yourself.

Vérifier si l’application est déjà installéeCheck to see if the app is already installed

Tout d’abord, vous voudrez vérifier si votre application teams est déjà installée pour les utilisateurs à partir desquels vous souhaitez l’installer, comme illustré dans l’exemple.First, you'll want to check to see if your Teams app is already installed for the users you want to install it from, as shown in the example.

GET /users/{user-id}/teamwork/installedApps?$expand=teamsAppDefinition&$filter=teamsAppDefinition/teamsAppId eq '{teamsAppid}'

{teamsAppId} est le id dans le manifeste de l’application teams que vous avez noté précédemment.Where {teamsAppId} is the id in the Teams app manifest that you made note of previously. Notez que cette opération peut être différente de votre appid pour les appels Microsoft Graph, et de votre botId .Note that this might be different from your appid for Microsoft Graph calls, and from your botId. Il peut s’avérer utile d’installer manuellement l’application pour un utilisateur et de tester l’appel auprès de cet utilisateur afin de s’assurer que vous disposez de la id valeur correcte.You might find it useful to manually install the app for a user and test the call against that user to ensure that you've got the correct id value.

L’appel renverra un tableau vide si l’application n’est pas installée ou un tableau avec un seul teamsAppInstallation si elle est déjà installée.The call will return an empty array if the app is not installed, or an array with a single teamsAppInstallation if it is already installed.

Installer l’applicationInstall the app

Si l’application n’est pas déjà installée pour cet utilisateur, vous pouvez l’installer comme indiqué dans l’exemple suivant.If the app is not already installed for that user, you can then install it as shown in the following example.

POST /users/{user-id}/teamwork/installedApps
{
   "teamsApp@odata.bind" : "https://graph.microsoft.com/beta/appCatalogs/teamsApps/{teamsAppid}"
}

Pour plus d’informations, consultez la rubrique installer une application pour l’utilisateur.For more information, see Install app for user.

Si Microsoft teams est en cours d’exécution sur l’utilisateur, il se peut que l’installation de l’application soit invisible ou non immédiatement.If the user has Microsoft Teams running, they might or might not see the app installation right away – they might need to restart the app to see the installation.

Obtenir l’ID du fil de conversationGet the chat thread ID

Lorsque l’application est installée pour l’utilisateur, le bot obtient un conversationUpdate événement qui contiendra les informations nécessaires pour envoyer le message proactif.When the app is installed for the user, the bot will get a conversationUpdate event that will contain the necessary information for it to send the proactive message. Pour plus d’informations, consultez la rubrique bot Events.For more information, see Bot events.

Si vous perdez le chatThreadId , vous pouvez le trouver à nouveau en appelant :If you lose the chatThreadId, you can find it again by calling:

GET /users/{user-id}/chats?$filter=installedApps/any(a:a/teamsApp/id eq '{teamsAppid}')

La propriété ID du résultat est l’ID chatThread.The id property of the result is the chatThread ID.

Envoi du messageSending the message

Maintenant que votre bot dispose des informations nécessaires, vous pouvez Envoyer un message proactif.Now that your bot has the necessary information, you can send a proactive message.

Exemple C#C# sample

Consultez https://github.com/microsoftgraph/contoso-airlines-teams-sample/tree/nkramer-promsg (note The Branch).See https://github.com/microsoftgraph/contoso-airlines-teams-sample/tree/nkramer-promsg (note the branch). Le code intéressant se trouve dans InstallAppToAllUsers() GraphService.cs.Interesting code is in InstallAppToAllUsers() in GraphService.cs.