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 la Microsoft API 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 au manifeste de votre application avec les valeurs suivantes :

  • id : ID de votre application Azure Active Directory
  • ressource : URL de ressource pour l’application

Remarque

  • 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 Azure Active Directory doit explicitement accorder des autorisations à une application. Une fois les autorisations accordées à l’application, tous les membres du client Microsoft Azure Active Directory obtiennent les autorisations accordées.

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

Importante

Microsoft Graph ne peut installer que les applications publiées sur l’App Store de votre organisation ou le magasin Teams.

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

    Microsoft Référence de la page 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 votre manifeste d’application Teams :

    {
      "value": [
        {
          "id": "b1c5353a-7aca-41b3-830f-27d5218fe0e5",
          "externalId": "f31b1263-ba99-435a-a679-911d24850d7c",
          "name": "Test App",
          "version": "1.0.1",
          "distributionMethod": "Organization"
        }
      ]
    }
    
  • Si votre application a déjà été chargée ou chargée de manière indépendante pour un utilisateur dans une étendue personnelle :

    Microsoft de référence sur la page Graph :Répertorier 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 ou chargée de manière test pour un canal dans l’étendue de l’équipe :

    Microsoft De référence sur la page Graph :Lister 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 actuellement installé pour un destinataire de message

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

Microsoft de référence sur la page Graph :Répertorier 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 :

Microsoft De référence sur la page 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.

Microsoft Référence de la page 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