Bot de notification interactive dans Teams

Article
04/24/2024

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 notification carte s’intègre facilement à un bot et fournit une expérience utilisateur cohérente au sein de l’application Bot.

Remarque

L’application de bot doit être installée avec l’étendue correspondante avant d’envoyer une notification.

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 :

Événement	Comportement
La première fois que vous installez un bot sur une personne, un groupe ou une équipe.	Ajoutez la référence de conversation cible au stockage.
Lorsque le bot est désinstallé d’une personne, d’un groupe ou d’une équipe.	Supprimez la référence de conversation cible du stockage.
Lorsque l’équipe installée par le bot est supprimée.	Supprimez la référence de conversation cible du stockage.
Lorsque l’équipe installée par le bot est restaurée.	Ajoutez la référence de conversation cible au stockage.
Quand le bot envoie des messages.	Lorsque la référence de conversation cible n’existe pas, ajoutez-la au stockage.

nouvel exemple d’événement de notification

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 :

TypeScript
C#

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

ajouter une étendue d’installation

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 :
  - Create un nouveau 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 Azure Functions déclencheurs de support.

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 carte et la carte adaptative s’effectue en faisant correspondre un 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(...);
    }
}

// list all installation targets
foreach (var target in await _conversation.Notification.GetInstallationsAsync()) {
    // "Person" means this bot is installed as Personal app
    if (target.Type == NotificationTargetType.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(...);
            }
        }

}

// list all installation targets
foreach (var target in await _conversation.Notification.GetInstallationsAsync()) {
    // "Group" means this bot is installed to a Group Chat
    if (target.Type == NotificationTargetType.Group)
    {
        // Directly notify the Group Chat
        await target.SendAdaptiveCard(...);
    // List all members in the Group Chat then notify each member
        var members = await target.GetMembersAsync();
        foreach (var member in 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(...);
        }
    }
}

// list all installation targets
foreach (var target in await _conversation.Notification.GetInstallationsAsync()) {
    // "Channel" means this bot is installed to a Team (default to notify General channel)
    if (target.Type == NotificationTargetType.Channel)
    {
        // Directly notify the Team (to the default General channel)
        await target.SendAdaptiveCard(...);

        // List all members in the Team then notify each member
        var members = await target.GetMembersAsync();
        foreach (var member in members) {
            await member.SendAdaptiveCard(...);
        }

        // List all channels in the Team then notify each channel
        var channels = await target.GetChannelsAsync();
        foreach (var channel in 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.

Remarque

Le code est généré dans le projet.

JavaScript/TypeScript
C#

/** 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 :

TypeScript
C#

// 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 propre 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.

Remarque

Il est recommandé d’utiliser votre propre stockage partagé pour l’environnement de production.
Si vous implémentez le stockage de votre propre Kit de développement logiciel (SDK) Bot Framework, par exemple , botbuilder-azure-blobs.BlobsStoragevous devez implémenter un autre stockage pour la notification. Vous pouvez partager la même chaîne de connexion d’objet blob avec différents conteneurs.

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 de fonction si vous sélectionnez Azure Functions pour héberger votre bot de notification.
Utilisez un jeton d’accès émis par Microsoft Entra ID. Pour plus d’informations, consultez Configurer l’authentification unique pour votre bot dans Microsoft Entra ID.

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 :

Create une application de bot Teams.
Create webhook entrant Teams.

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

	Application bot Teams	Webhook entrant Teams
Message personne individuelle	✔️	❌
Conversation de groupe de messages	✔️	❌
Canal public de message	✔️	✔️
Canal privé de message	❌	✔️
Envoyer carte message	✔️	✔️
Envoyer un message de bienvenue	✔️	❌
Récupérer le contexte Teams	✔️	❌
Étapes d’installation requises dans Teams	✔️	❌
Exiger une ressource Azure	Azure Bot Service	❌

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 :

Create 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

Pourquoi les installations de notification sont-elles vides même si l’application bot est installée dans Teams ?

Teams envoie un événement uniquement lors de la première installation. Si l’application bot est déjà installée avant le lancement de votre service bot de notification, l’événement d’installation n’a pas atteint le service bot ou est omis.

Vous pouvez résoudre ce problème des manières suivantes :

Envoyez un message à votre bot personnel ou mention votre bot dans une conversation de groupe ou un canal, ce qui vous permet d’atteindre à nouveau le service bot avec les informations d’installation correctes.
Désinstallez l’application bot de Teams, puis réintroduisez-la ou relancez-la. Vous pouvez renvoyer l’événement d’installation au service de bot.

Les connexions cibles de notification sont stockées dans le stockage de persistance. Si vous utilisez le stockage de fichiers local par défaut, toutes les installations sont stockées sous .notification.localstore.json.

Remarque

Pour plus d’informations sur l’ajout de votre propre stockage, consultez Ajouter un stockage.

Pourquoi une erreur de requête incorrecte ou d’argument incorrect se produit lors de l’envoi d’une notification ?

Si l’installation de la notification ne correspond pas à l’ID ou au mot de passe du bot, vous pouvez obtenir une erreur Échec du déchiffrement de l’ID de conversation . L’une des causes possibles de cette erreur est que l’ID ou le mot de passe du bot est modifié en raison du nettoyage de l’état local ou du reprovisionnement.

Vous pouvez résoudre ce problème en nettoyant votre stockage de notifications. Après le nettoyage, informez dans Teams de réinstaller votre bot et vérifiez que la nouvelle installation est à jour. Chaque installation de notification stockée est liée à un seul bot. Si vous pouvez case activée votre stockage de notifications, son champ de bot doit correspondre au bot que vous exécutez, par exemple l’ID de bot avec le même GUID.

Remarque

En cas de stockage local, l’emplacement par défaut est .notification.localstore.json.

Pourquoi la cible de notification est perdue après le redémarrage ou le redéploiement de l’application bot ?

Les connexions cibles de notification sont stockées dans le stockage de persistance. Si vous utilisez le stockage de fichiers locaux par défaut, l’application web Azure et Azure Functions propre 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. Il est recommandé d’utiliser votre propre stockage partagé pour l’environnement de production.

Pourquoi une erreur non définie est-elle retournée lors de l’utilisation de l’API 'findChannel'() ?

Vous pouvez rencontrer une erreur non définie lorsque l’application de bot est installée dans d’autres canaux au lieu du General canal. Pour corriger cette erreur, vous pouvez désinstaller l’application bot de Teams, puis la relancer. Une fois que vous avez redéboqué et relancé, vérifiez que l’application de bot est installée dans le General canal.

Puis-je connaître toutes les cibles où mon bot est installé dans et hors du projet de notification ?

Il existe des API Microsoft Graph pour répertorier les applications installées dans une équipe, un groupe ou une conversation. Si nécessaire, itérer votre équipe, grouper ou discuter dans une application installée à cibler. Dans le projet de notification, il utilise le stockage de persistance pour stocker les cibles d’installation. Pour plus d’informations, consultez notification basée sur des événements.

Comment personnaliser les ports d’écoute Azurite ?

Si Azurite se ferme en raison du port utilisé, vous pouvez spécifier un autre port d’écoute et mettre à jour le chaîne de connexion de AzureWebJobsStorage dans local.settings.json.

Comment étendre mon bot de notification pour prendre en charge la commande et la réponse ?

Accédez à bot\src\internal\initialize.ts(js) et mettez à jour votre conversationBot initialisation pour activer la fonctionnalité de notification :
Pour ajouter une commande à votre bot, suivez les instructions fournies dans Bot de commande dans Teams.

Comment étendre mon bot de notification en ajoutant des actions de carte adaptative de bot de flux de travail ?

La fonctionnalité gestionnaire d’actions de carte adaptative permet à l’application de répondre aux actions de carte adaptative déclenchées par les utilisateurs finaux pour effectuer un workflow séquentiel. Une carte adaptative fournit un ou plusieurs boutons dans le carte pour demander l’entrée de l’utilisateur, par exemple, appeler certaines API. La carte adaptative envoie ensuite une autre carte adaptative dans la conversation pour répondre à l’action carte.

Pour plus d’informations sur l’ajout d’actions de carte adaptatives à un bot de commande, consultez Bot de flux de travail dans Teams.

Retour en haut

Guide pas à pas

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

Bot de notification interactive dans Teams

Notification basée sur des événements

Installation du bot de notification

Personnaliser la notification

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 l’initialisation

Personnaliser l’adaptateur

Ajouter de l'espace de stockage

Ajouter l’authentification pour l’API de notification

Se connecter à des API existantes

Application de bot Teams ou webhook entrant Teams

Notification webhook entrante

Envoi des notifications de flux d’activités

FAQ

Guide pas à pas

Voir aussi

Commentaires

Ressources supplémentaires