Partager via


Envoyer des messages d’installation proactive

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

  1. 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.

  2. 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 :

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.");
}

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

Voir aussi