Bot de notification interactive dans Teams

Microsoft Teams Toolkit vous permet de créer des applications qui capturent des événements et les envoient sous forme de notifications interactives à une conversation personnelle, de groupe ou à un canal dans Microsoft Teams. Vous pouvez envoyer des notifications sous forme de texte brut ou de cartes adaptatives. Le modèle de bot de notification crée une application qui envoie un message à Teams avec des cartes adaptatives déclenchées par une requête http post.

Le modèle d’application est créé à l’aide du Kit de développement logiciel (SDK) TeamsFx, qui fournit un ensemble simple de fonctions sur Microsoft Bot Framework pour implémenter vos besoins. Par exemple, une agence de voyage crée une application dans Teams pour ses utilisateurs afin de les tenir à jour avec les prévisions météorologiques. Dans l’organigramme suivant, une application Teams informe les utilisateurs des prévisions météorologiques à l’aide d’une carte adaptative :

Vous pouvez envoyer une notification de bot dans les scénarios suivants :

• Vous souhaitez informer tous les utilisateurs d’un canal ou d’une conversation concernant le même contenu ou le contenu associé.

• Interface utilisateur hautement personnalisable dans une carte

• Vous avez besoin d’une réponse rapide, d’inclure du contenu multimédia ou des boutons d’action.

• Envoyer des notifications planifiées

• Allumer des badges doubles sur l’activité et la conversation, le canal ou l’application

• Ajouter un modèle dans le code source.

• Gestion manuelle de la localisation.

Avantages

• Facilite les notifications vers une conversation personnelle, de groupe et dans un canal, à l’aide des API du Kit de développement logiciel (SDK) TeamsFx.

• Améliore l’expérience utilisateur en personnalisant la notification avec une carte adaptative.

• Fournit plusieurs mécanismes pour déclencher des notifications telles que http et déclencheur de minuteur de planification avec Azure Functions.

• Une carte de notification s’intègre facilement à un bot et fournit une expérience utilisateur cohérente au sein de l’application Bot.

Retour en haut

Notification basée sur des événements

Le Kit de développement logiciel (SDK) Bot Framework fournit les fonctionnalités nécessaires pour envoyer des messages de manière proactive dans Teams. Le Kit de développement logiciel (SDK) TeamsFx fournit les fonctionnalités permettant de gérer les références de conversation du bot lorsqu’un événement de bot est déclenché. Le Kit de développement logiciel (SDK) TeamsFx reconnaît les événements de bot suivants :

Lorsque vous envoyez des notifications, le Kit de développement logiciel (SDK) TeamsFx crée une conversation à partir de la référence de conversation sélectionnée, puis envoie un message. Pour une utilisation avancée, vous pouvez accéder directement à la référence de conversation pour exécuter votre propre logique de bot :

// list all installation targets
for (const target of await notificationApp.notification.installations()) {
    // call Bot Framework's adapter.continueConversationAsync()
    await target.adapter.continueConversationAsync(
        target.botAppId,
        target.conversationReference,
        async (context) => {
            // your own bot logic
            await context...
        }
    );
}

   // list all installation targets
    foreach (var target in await _conversation.Notification.GetInstallationsAsync()) {
    // call Bot Framework's adapter.ContinueConversationAsync()
    await target.Adapter.ContinueConversationAsync(
        target.BotAppId,
        target.ConversationReference,
        async (context, ctx) =>
        {
            // your own bot logic
            await context...
        },
        cancellationToken);
}

Retour en haut

Installation du bot de notification

Un bot de notification doit être installé dans une équipe, une conversation de groupe ou en tant qu’application personnelle, selon l’étendue requise. Vous devez sélectionner la cible d’installation avant d’ajouter le bot à votre application.

Pour plus d’options d’installation, consultez Configurer les options d’installation par défaut. Pour la désinstallation, consultez Supprimer une application de Teams.

Retour en haut

Personnaliser la notification

Vous pouvez effectuer les personnalisations suivantes pour étendre le modèle de notification en fonction des besoins de votre entreprise :

• Personnaliser le point de déclencheur à partir de la source de l’événement
• Personnaliser le contenu de la notification
• Personnaliser l’emplacement d’envoi des notifications

Personnaliser le point de déclencheur à partir de la source de l’événement

Vous pouvez personnaliser les déclencheurs suivants :

• Restify notification basée sur :

  • Lorsqu’une requête HTTP est envoyée au src/index.js point d’entrée, l’implémentation par défaut envoie une carte adaptative à Teams. Vous pouvez personnaliser cet événement en src/index.jsmodifiant . Une implémentation classique peut appeler une API pour récupérer des événements, des données, ou les deux, qui peuvent envoyer une carte adaptative en fonction des besoins. Vous pouvez effectuer les opérations suivantes pour ajouter d’autres déclencheurs :

    • Créez un routage : server.post("/api/new-trigger", ...).
    • Ajoutez des déclencheurs de minuteur à partir de packages npm largement utilisés, tels que cron, node-schedule ou à partir d’autres packages.

    Remarque

    Par défaut, Teams Toolkit crée une structure d’un point d’entrée unique restify dans src/index.js.

• Notification basée sur Azure Functions :

  • Lorsque vous sélectionnez timer déclencheur, le déclencheur src/timerTrigger.ts de minuteur De fonction Azure implémenté par défaut envoie une carte adaptative toutes les 30 secondes. Vous pouvez modifier le fichier *Trigger/function.json pour personnaliser la schedule propriété. Pour plus d’informations, consultez la documentation Azure Function.

    

  • Lorsque vous sélectionnez http déclencheur, la requête HTTP déclenche la notification et l’implémentation par défaut envoie une carte adaptative à Teams. Vous pouvez modifier cet événement en personnalisant src/*Trigger.ts. Cette implémentation peut appeler une API pour récupérer des événements, des données, ou les deux, qui peut envoyer une carte adaptative en fonction des besoins.

    

• Déclencheurs de fonction Azure :

  • Event Hub pour envoyer des notifications lorsqu’un événement est envoyé (push) à Azure Event Hub.

  • Cosmos DB pour envoyer des notifications lorsqu’un document Cosmos est créé ou mis à jour.

Pour plus d’informations sur les déclencheurs de support, consultez Déclencheurs de prise en charge d’Azure Functions.

Personnaliser le contenu de la notification

Le fichier src/adaptiveCards/notification-default.json définit la carte adaptative par défaut. Vous pouvez utiliser le concepteur de cartes adaptatives pour vous aider à concevoir visuellement l’interface utilisateur de votre carte adaptative. Définit src/cardModels.ts une structure de données utilisée pour charger des données pour la carte adaptative. La liaison entre le modèle de carte et la carte adaptative s’effectue en faisant correspondre le nom, tel que CardData.title mappé à ${title} dans la carte adaptative. Vous pouvez ajouter, modifier ou supprimer des propriétés et leurs liaisons pour personnaliser la carte adaptative en fonction des besoins.

Vous pouvez également ajouter de nouvelles cartes si nécessaire. Pour plus d’informations sur la création de différents types de cartes adaptatives avec une liste ou une table des matières dynamiques à l’aide ColumnSet de et FactSet, consultez Exemple de notification de carte adaptative.

Personnaliser l’emplacement d’envoi des notifications

Vous pouvez personnaliser l’envoi de la notification aux cibles suivantes :

• Notifications à une conversation personnelle :

  • TypeScript
  • C#

  // list all installation targets
  for (const target of await notificationApp.notification.installations()) {
      // "Person" means this bot is installed as Personal app
      if (target.type === "Person") {
          // Directly notify the individual person
          await target.sendAdaptiveCard(...);
      }
  }
  

• Notifications à une conversation de groupe :

  • TypeScript
  • C#

  // list all installation targets
  for (const target of await notificationApp.notification.installations()) {
      // "Group" means this bot is installed to a Group Chat
      if (target.type === "Group") {
          // Directly notify the Group Chat
          await target.sendAdaptiveCard(...);
  
              // List all members in the Group Chat then notify each member
              const members = await target.members();
              for (const member of members) {
                  await member.sendAdaptiveCard(...);
              }
          }
  
  }
  

• Notifications sur un canal :

  • TypeScript
  • C#

  // list all installation targets
  for (const target of await notificationApp.notification.installations()) {
      // "Channel" means this bot is installed to a Team (default to notify General channel)
      if (target.type === "Channel") {
          // Directly notify the Team (to the default General channel)
          await target.sendAdaptiveCard(...);
  
          // List all members in the Team then notify each member
          const members = await target.members();
          for (const member of members) {
              await member.sendAdaptiveCard(...);
          }
  
          // List all channels in the Team then notify each channel
          const channels = await target.channels();
          for (const channel of channels) {
              await channel.sendAdaptiveCard(...);
          }
      }
  }
  

• Notifications à un canal spécifique :

  // find the first channel when the predicate is true.
  const channel = await notificationApp.notification.findChannel(c => Promise.resolve(c.info.name === "MyChannelName"));
  
  // send adaptive card to the specific channel.
  await channel?.sendAdaptiveCard(...);
  

  Remarque

  Pour empêcher une sortie non définie, veillez à installer l’application bot dans le canal Général d’une équipe.

• Notifications à une personne spécifique :

  // find the first person when the predicate is true.
  const member = await notificationApp.notification.findMember(m => Promise.resolve(m.account.name === "Bob"));
  
  // send adaptive card to the specific person. 
  await member?.sendAdaptiveCard(...);
  

  Remarque

  Pour éviter une sortie non définie et une notification manquante, vous devez inclure la personne spécifique dans l’étendue d’installation de la notification.

Retour en haut

Personnaliser l’initialisation

Vous devez créer ConversationBot pour envoyer une notification.

/** Javascript/Typescript: src/internal/initialize.*s **/
const notificationApp = new ConversationBot({
    // The bot id and password to create CloudAdapter.
    // See https://aka.ms/about-bot-adapter to learn more about adapters.
    adapterConfig: {
        MicrosoftAppId: config.botId,
        MicrosoftAppPassword: config.botPassword,
        MicrosoftAppType: "MultiTenant",
    },
    // Enable notification
    notification: {
        enabled: true,
    },
});

/** .NET: Program.cs or Startup.cs **/
// Create the Conversation with notification feature enabled.
builder.Services.AddSingleton(sp =>
{
    var options = new ConversationOptions()
    {
        // To use your own CloudAdapter
        Adapter = sp.GetService<CloudAdapter>(),
        Notification = new NotificationOptions
        {
            BotAppId = builder.Configuration["MicrosoftAppId"],
        },
    };

    return new ConversationBot(options);
});

Retour en haut

Personnaliser l’adaptateur

Vous pouvez personnaliser en créant votre propre adaptateur ou en personnalisant l’adaptateur après l’initialisation. Voici l’exemple de code pour la création de votre adaptateur :

// Create your own adapter
const adapter = new CloudAdapter(...);

// Customize your adapter, e.g., error handling
adapter.onTurnError = ...

const notificationApp = new ConversationBot({
    // use your own adapter
    adapter: adapter;
    ...
});

// Or, customize later
notificationApp.adapter.onTurnError = ...

Retour en haut

Ajouter de l'espace de stockage

Le stockage peut être utilisé pour implémenter des connexions de notification. Vous pouvez ajouter votre propre stockage à l’aide de l’exemple de code suivant :

// implement your own storage
class MyStorage implements NotificationTargetStorage {...}
const myStorage = new MyStorage(...);

// initialize ConversationBot with notification enabled and customized storage
const notificationApp = new ConversationBot({
    // The bot id and password to create CloudAdapter.
    // See https://aka.ms/about-bot-adapter to learn more about adapters.
    adapterConfig: {
        MicrosoftAppId: config.botId,
        MicrosoftAppPassword: config.botPassword,
        MicrosoftAppType: "MultiTenant",
    },
    // Enable notification
    notification: {
        enabled: true,
        storage: myStorage,
    },
});

// implement your own storage
public class MyStorage : INotificationTargetStorage {...}

// initialize ConversationBot with notification enabled and customized storage
builder.Services.AddSingleton(sp =>
{
    var options = new ConversationOptions()
    {
        Adapter = sp.GetService<CloudAdapter>(),
        Notification = new NotificationOptions
        {
            BotAppId = builder.Configuration["MicrosoftAppId"],
            // Use your own storage
            Storage = new MyStorage(),
        },
    };

    return new ConversationBot(options);
});

Si le stockage n’est pas fourni, vous pouvez utiliser un stockage de fichiers local par défaut, qui stocke les connexions de notification dans :

• .notification.localstore.json en cas d’exécution locale.
• ${process.env.TEMP}/.notification.localstore.json, si process.env.RUNNING_ON_AZURE a la valeur 1.

Si vous utilisez le stockage de fichiers locaux par défaut, l’application web Azure et Azure Functions nettoient le fichier local lors d’un redémarrage ou d’un redéploiement. Vous pouvez également désinstaller le bot de Teams, puis l’installer pour ajouter à nouveau des connexions au stockage.

Le NotificationTargetStorage est différent du stockage personnalisé du Kit de développement logiciel (SDK) Bot Framework. Le stockage de notifications nécessite readdes fonctionnalités , deletewrite, et list , mais le stockage du Kit de développement logiciel (SDK) Bot Framework a readdes fonctionnalités , writeet delete et n’a pas les list fonctionnalités.

Pour plus d’informations sur le stockage d’objets blob Azure, consultez l’exemple d’implémentation de stockage de notification.

Retour en haut

Ajouter l’authentification pour l’API de notification

Si vous sélectionnez déclencheur HTTP, l’API de notification générée automatiquement n’a pas d’authentification ou d’autorisation activée. Veillez à ajouter l’authentification ou l’autorisation pour l’API avant de l’utiliser pour la production. Vous pouvez effectuer l’une des actions suivantes :

• Utilisez une clé API. Vous pouvez utiliser des clés d’accès aux fonctions si vous sélectionnez Azure Functions pour héberger votre bot de notification.

• Utilisez un jeton d’accès émis par l’ID Microsoft Entra. Pour plus d’informations, consultez Configurer l’authentification unique pour votre bot dans l’ID Microsoft Entra.

Il peut y avoir d’autres solutions d’authentification ou d’autorisation pour une API, que vous pouvez sélectionner si nécessaire.

Retour en haut

Se connecter à des API existantes

Si vous ne disposez pas du KIT de développement logiciel (SDK) requis et que vous souhaitez appeler des API externes dans votre code, la commande Teams : Se connecter à une API dans l’extension Microsoft Visual Studio Code Teams Toolkit, ou la commande teamsfx add api-connection dans TeamsFx CLI peuvent être utilisées pour démarrer le code afin d’appeler des API cibles. Pour plus d’informations, consultez Intégrer des API tierces existantes.

Application de bot Teams ou webhook entrant Teams

TeamsFx prend en charge deux façons de vous aider à envoyer des notifications de votre système à Teams :

• Créez une application de bot Teams.
• Créer un webhook entrant Teams.

Dans le tableau suivant, vous pouvez voir la comparaison des deux façons différentes :

Notification webhook entrante

Les webhooks entrants vous permettent de publier des messages à partir d’applications Teams. Si les webhooks entrants sont activés pour une équipe dans n’importe quel canal, ils exposent le point de terminaison HTTPS, qui accepte le format JSON correctement mis en forme et insère les messages dans ce canal. Par exemple, vous pouvez créer un webhook entrant dans votre canal DevOps, configurer votre build et déployer et surveiller simultanément les services pour envoyer des alertes. TeamsFx vous fournit un exemple de notification de webhook entrant qui vous permet d’effectuer les tâches suivantes :

• Créez un webhook entrant dans Teams.
• Envoyer des notifications à l’aide de webhooks entrants avec des cartes adaptatives.

Retour en haut

Envoi des notifications de flux d’activités

Si vous souhaitez envoyer des notifications de flux d’activité pour votre application, vous pouvez utiliser les API de notification de flux d’activité dans Microsoft Graph. Pour plus d’informations, consultez Envoyer des notifications de flux d’activité aux utilisateurs dans Microsoft Teams.

FAQ

Retour en haut

Guide pas à pas

Suivez le guide pas à pas pour créer un bot de notification Teams.

Voir aussi

• Concepts de base d’une conversation
• Créer des bots pour Teams
• Créer votre première application de bot à l’aide de JavaScript
• Messages proactifs
• Cartes adaptatives
• Kit de développement logiciel (SDK) TeamsFx
• Kit de développement logiciel (SDK) Bot Framework
• Envoyer des messages d’installation proactive
• Créer votre application à l’aide de C#