Envoyer des messages d’installation proactive

Article
06/26/2024

Messagerie proactive dans Teams

Les messages proactifs sont lancés par les bots pour démarrer des conversations avec un utilisateur. Ils servent de nombreux objectifs, notamment l’envoi de messages d’accueil, la réalisation d’enquêtes ou de sondages et la diffusion de notifications à l’échelle de l’organisation. Les messages proactifs dans Teams peuvent être remis en tant que conversations ad hoc ou basées sur des dialogues :

Type de message	Description
Message proactif ad hoc	Le robot interjecte un message sans interrompre le flux de la conversation.
Message proactif basé sur une boîte de dialogue	Le bot crée un thread de dialogue, prend le contrôle d’une conversation, remet le message proactif, ferme et retourne le contrôle à la boîte de dialogue précédente.

Installation proactive d’applications dans Teams

Pour que votre bot puisse faire passer un message proactif à un utilisateur, il doit être installé en tant qu’application personnelle ou dans une équipe où l’utilisateur est membre. Parfois, vous devez envoyer des messages proactifs aux utilisateurs qui n’ont pas installé ou qui n’ont pas déjà interagi avec votre application. Par exemple, si vous devez envoyer des informations importantes à tous les membres de votre organisation, vous pouvez utiliser l’API Microsoft Graph pour installer de manière proactive votre bot pour vos utilisateurs.

Autorisations

Les autorisations de type de ressource Microsoft Graph teamsAppInstallation vous aident à gérer le cycle de vie d’installation de votre application pour toutes les étendues d’utilisateur (personnel) ou d’équipe (canal) au sein de la plateforme Microsoft Teams :

Autorisation d’application	Description
`TeamsAppInstallation.ReadWriteSelfForUser.All`	Permet à une application Teams de lire, d’installer, de mettre à niveau et de désinstaller elle-même pour n’importe quel utilisateur, sans connexion ni utilisation préalable.
`TeamsAppInstallation.ReadWriteSelfForTeam.All`	Permet à Teams de lire, d’installer, de mettre à jour et de se désinstaller elle-même dans une équipe, sans utilisateur connecté.

Pour utiliser ces autorisations, vous devez ajouter une clé webApplicationInfo à votre manifeste d’application (précédemment appelé manifeste d’application Teams) avec les valeurs suivantes :

id : votre ID d’application Microsoft Entra.
ressource : URL de ressource pour l’application

Notes

Votre bot nécessite des autorisations d’application et non des autorisations déléguées par l’utilisateur, car l’installation est destinée à d’autres utilisateurs.
Un administrateur de locataire Microsoft Entra doit accorder explicitement des autorisations à une application. Une fois que l’application dispose d’autorisations, tous les membres du locataire Microsoft Entra obtiennent les autorisations accordées.

Activer l’installation proactive du bot et de la messagerie proactive

Importante

Microsoft Graph peut uniquement installer les applications publiées dans l’App Store de votre organisation ou dans le Microsoft Teams Store.

Créer et publier votre bot de messagerie proactive pour Teams

Pour commencer, vous avez besoin d’un bot pour Teams avec des fonctionnalités de messagerie proactive qui se trouve dans l’App Store de votre organisation ou le Magasin Teams.

Conseil

Le modèle d’application Company Communicator prêt pour la production autorise la messagerie de diffusion et constitue un bon point de départ pour créer votre application de bot proactive.

Obtenir `teamsAppId` pour votre application

Vous pouvez effectuer ce teamsAppId des façons suivantes :

À partir du catalogue d’applications de votre organisation :

Informations de référence sur la page Microsoft Graph :teamsApp, type de ressource

Demande HTTP GET :
```
GET https://graph.microsoft.com/v1.0/appCatalogs/teamsApps?$filter=externalId eq '{IdFromManifest}'
```
La demande doit retourner un teamsApp objet id, qui est l’ID d’application généré par le catalogue de l’application. Cela diffère de l’ID que vous avez fourni dans le manifeste de votre application :
```
{
  "value": [
    {
      "id": "b1c5353a-7aca-41b3-830f-27d5218fe0e5",
      "externalId": "f31b1263-ba99-435a-a679-911d24850d7c",
      "name": "Test App",
      "version": "1.0.1",
      "distributionMethod": "Organization"
    }
  ]
}
```
Notes

Lorsque l’application se trouve dans le Magasin Teams, est teamsAppId identique à IdFromManifest et ne externalId doit pas être utilisé dans ce cas.
Si votre application a déjà été chargée pour un utilisateur dans l’étendue personnelle :

Informations de référence sur la page Microsoft Graph :Lister les applications installées pour l’utilisateur

Demande HTTP GET :
```
GET https://graph.microsoft.com/v1.0/users/{user-id}/teamwork/installedApps?$expand=teamsApp&$filter=teamsApp/externalId eq '{IdFromManifest}'
```
Si votre application a déjà été chargée pour un canal dans l’étendue de l’équipe :

Informations de référence sur la page Microsoft Graph :Répertorier les applications dans l’équipe

Demande HTTP GET :
```
GET https://graph.microsoft.com/v1.0/teams/{team-id}/installedApps?$expand=teamsApp&$filter=teamsApp/externalId eq '{IdFromManifest}'
```
Conseil

Pour affiner la liste des résultats, vous pouvez filtrer n’importe quel champ de l’objet teamsApp.

Déterminer si votre bot est installé pour un destinataire de message

Vous pouvez déterminer si votre bot est installé pour un destinataire de message comme suit :

Informations de référence sur la page Microsoft Graph :Lister les applications installées pour l’utilisateur

Demande HTTP GET :

GET https://graph.microsoft.com/v1.0/users/{user-id}/teamwork/installedApps?$expand=teamsApp&$filter=teamsApp/id eq '{teamsAppId}'

La requête renvoie aux :

Tableau vide si l’application n’est pas installée.
Tableau avec un objet teamsAppInstallation unique si l’application est installée.

Installez votre application.

Vous pouvez installer votre application comme suit :

Informations de référence sur la page Microsoft Graph :Installer l’application pour l’utilisateur

Demande HTTP POST

POST https://graph.microsoft.com/v1.0/users/{user-id}/teamwork/installedApps
Content-Type: application/json

{
   "teamsApp@odata.bind" : "https://graph.microsoft.com/v1.0/appCatalogs/teamsApps/{teamsAppId}"
}

Si l’utilisateur a Microsoft Teams en cours d’exécution, l’installation de l’application se produit immédiatement. Un redémarrage peut être nécessaire pour afficher l’application installée.

Récupérer la conversation `chatId`

Lorsque votre application est installée pour l’utilisateur, le bot reçoit une notification d’événementconversationUpdate qui contient les informations nécessaires pour envoyer le message proactif.

Informations de référence sur la page Microsoft Graph :Obtenir une conversation

Vous devez disposer de {teamsAppInstallationId}votre application . Si vous ne l’avez pas, utilisez les éléments suivants :

Demande HTTP GET :
```
GET https://graph.microsoft.com/v1.0/users/{user-id}/teamwork/installedApps?$expand=teamsApp&$filter=teamsApp/id eq '{teamsAppId}'
```
La propriété id de la réponse est le teamsAppInstallationId.
Effectuez la requête suivante pour récupérer les chatIdéléments suivants :

Requête HTTP GET (autorisation—TeamsAppInstallation.ReadWriteSelfForUser.All ) :
```
GET https://graph.microsoft.com/v1.0/users/{user-id}/teamwork/installedApps/{teamsAppInstallationId}/chat
```
La propriété id de la réponse est le chatId.

Vous pouvez également récupérer la chatId requête avec la suivante, mais elle nécessite l’autorisation plus large Chat.Read.All :

Requête HTTP GET (autorisation—Chat.Read.All ) :
```
GET https://graph.microsoft.com/v1.0/users/{user-id}/chats?$filter=installedApps/any(a:a/teamsApp/id eq '{teamsAppId}')
```

Envoyer des messages proactifs

Votre bot peut envoyer des messages proactifs une fois le bot ajouté pour un utilisateur ou une équipe et avoir reçu toutes les informations utilisateur.

Extraits de code

Le code suivant fournit un exemple d’envoi de messages proactifs :

C#
Node.js

public async Task<int> SendNotificationToAllUsersAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
{
   int msgSentCount = 0;

   // Send notification to all the members.
   foreach (var conversationReference in _conversationReferences.Values)
   {
       await turnContext.Adapter.ContinueConversationAsync(_configuration["MicrosoftAppId"], conversationReference, BotCallback, cancellationToken);
       msgSentCount++;
   }

   return msgSentCount;
}

private async Task BotCallback(ITurnContext turnContext, CancellationToken cancellationToken)
{
    // Sends an activity to the sender of the incoming activity.
   await turnContext.SendActivityAsync("Proactive hello.");
}

server.get('/api/notify', async (req, res) => {
    for (const conversationReference of Object.values(conversationReferences)) {

        // Sends a proactive message to a conversation.
        await adapter.continueConversationAsync(process.env.MicrosoftAppId, conversationReference, async context => {
            await context.sendActivity('proactive hello');
        });
    }
    res.setHeader('Content-Type', 'text/html');
    res.writeHead(200);
    res.write('<html><body><h1>Proactive messages have been sent.</h1></body></html>');
    res.end();
});

Exemple de code

Exemple de nom	Description	.NET	Node.js
Installation proactive de l’application et envoi de notifications proactives	Cet exemple indique comment utiliser l’installation proactive de l’application pour les utilisateurs et envoyer des notifications proactives en appelant les API Microsoft Graph.	View	View

Exemples de code d’application de messagerie supplémentaires

Exemples de code Teams de messagerie proactive

Partager via

Envoyer des messages d’installation proactive

Messagerie proactive dans Teams

Installation proactive d’applications dans Teams

Autorisations

Activer l’installation proactive du bot et de la messagerie proactive

Créer et publier votre bot de messagerie proactive pour Teams

Obtenir `teamsAppId` pour votre application

Déterminer si votre bot est installé pour un destinataire de message

Installez votre application.

Récupérer la conversation `chatId`

Envoyer des messages proactifs

Extraits de code

Exemple de code

Exemples de code d’application de messagerie supplémentaires

Voir aussi

Ressources supplémentaires

Partager via

Envoyer des messages d’installation proactive

Messagerie proactive dans Teams

Installation proactive d’applications dans Teams

Autorisations

Activer l’installation proactive du bot et de la messagerie proactive

Créer et publier votre bot de messagerie proactive pour Teams

Obtenir teamsAppId pour votre application

Déterminer si votre bot est installé pour un destinataire de message

Installez votre application.

Récupérer la conversation chatId

Envoyer des messages proactifs

Extraits de code

Exemple de code

Exemples de code d’application de messagerie supplémentaires

Voir aussi

Ressources supplémentaires

Obtenir `teamsAppId` pour votre application

Récupérer la conversation `chatId`