Événements de conversation dans votre robot Teams

Important

Les exemples de code de cette section sont basés sur la version 4.6 et les versions ultérieures du SDK Bot Framework. Si vous recherchez de la documentation pour les versions antérieures, consultez la section bots - V3 SDK dans le dossier Ressources de la documentation.

Lorsque vous construisez vos bots de conversation Microsoft Teams, vous pouvez utiliser des événements de conversation. Teams envoie des notifications à votre bot pour les événements de conversation qui se produisent dans les étendues où votre bot est actif. Vous pouvez capturer ces événements dans votre code et prendre les mesures suivantes :

  • Déclencher un message de bienvenue lorsque votre bot est ajouté à une équipe.
  • Déclencher un message de bienvenue lorsqu’un nouveau membre d’équipe est ajouté ou supprimé.
  • Déclencher une notification lorsqu’un canal est créé, renommé ou supprimé.
  • Lorsqu’un message bot est aimé par un utilisateur.

Événements de mise à jour de conversation

Vous pouvez utiliser les événements de mise à jour de conversation pour fournir de meilleures notifications et des actions de bot plus efficaces.

Important

  • Vous pouvez ajouter de nouveaux événements à tout moment et votre bot commence à les recevoir.
  • Vous devez concevoir votre bot pour recevoir des événements inattendus.
  • Si vous utilisez le SDK Bot Framework, votre bot répond automatiquement à tous les événements que vous choisissez de 200 - OK ne pas gérer.

Un bot reçoit un conversationUpdate événement dans l’un des cas suivants :

  • Lorsque le bot a été ajouté à une conversation.
  • D’autres membres sont ajoutés à une conversation ou supprimés d’une conversation.
  • Les métadonnées de conversation ont changé.

L’événement conversationUpdate est envoyé à votre robot lorsqu’il reçoit des informations sur les mises à jour d’appartenance pour les équipes dans lesquelles il a été ajouté. Il reçoit également une mise à jour lorsqu’elle a été ajoutée pour la première fois pour des conversations personnelles.

Le tableau suivant présente la liste des événements de Teams de conversation avec plus de détails :

Action EventType Méthode appelée Description Portée
Canal créé channelCreated OnTeamsChannelCreatedAsync Un canal est créé. Équipe
Canal renommé channelRenamed OnTeamsChannelRenamedAsync Un canal est renommé. Équipe
Canal supprimé channelDeleted OnTeamsChannelDeletedAsync Un canal est supprimé. Équipe
Canal restauré channelRestored OnTeamsChannelRestoredAsync Un canal est restauré. Équipe
Membres ajoutés membersAdded OnTeamsMembersAddedAsync Un membre est ajouté. Tous
Membres supprimés membersRemoved OnTeamsMembersRemovedAsync Un membre est supprimé. groupChat et équipe
Équipe renommée teamRenamed OnTeamsTeamRenamedAsync Une équipe est renommée. Équipe
Équipe supprimée teamDeleted OnTeamsTeamDeletedAsync Une équipe est supprimée. Équipe
Équipe archivée teamArchived OnTeamsTeamArchivedAsync Une équipe est archivée. Équipe
Équipe non archivée teamUnarchived OnTeamsTeamUnarchivedAsync Une équipe n’est pasarchive . Équipe
Équipe restaurée teamRestored OnTeamsTeamRestoredAsync Une équipe est restaurée Équipe

Canal créé

L’événement créé par le canal est envoyé à votre bot chaque fois qu’un nouveau canal est créé dans une équipe où votre bot est installé.

Le code suivant montre un exemple d’événement de canal créé :

protected override async Task OnTeamsChannelCreatedAsync(ChannelInfo channelInfo, TeamInfo teamInfo, ITurnContext<IConversationUpdateActivity> turnContext, CancellationToken cancellationToken)
{
    var heroCard = new HeroCard(text: $"{channelInfo.Name} is the Channel created");
    await turnContext.SendActivityAsync(MessageFactory.Attachment(heroCard.ToAttachment()), cancellationToken);
}

Canal renommé

L’événement renommé de canal est envoyé à votre bot chaque fois qu’un canal est renommé dans une équipe où votre bot est installé.

Le code suivant montre un exemple d’événement renommé de canal :

protected override async Task OnTeamsChannelRenamedAsync(ChannelInfo channelInfo, TeamInfo teamInfo, ITurnContext<IConversationUpdateActivity> turnContext, CancellationToken cancellationToken)
{
    var heroCard = new HeroCard(text: $"{channelInfo.Name} is the new Channel name");
    await turnContext.SendActivityAsync(MessageFactory.Attachment(heroCard.ToAttachment()), cancellationToken);
}

Canal supprimé

L’événement de canal supprimé est envoyé à votre bot, chaque fois qu’un canal est supprimé dans une équipe où votre bot est installé.

Le code suivant montre un exemple d’événement de suppression de canal :

protected override async Task OnTeamsChannelDeletedAsync(ChannelInfo channelInfo, TeamInfo teamInfo, ITurnContext<IConversationUpdateActivity> turnContext, CancellationToken cancellationToken)
{
    var heroCard = new HeroCard(text: $"{channelInfo.Name} is the Channel deleted");
    await turnContext.SendActivityAsync(MessageFactory.Attachment(heroCard.ToAttachment()), cancellationToken);
}

Canal restauré

L’événement de restauration de canal est envoyé à votre bot, chaque fois qu’un canal précédemment supprimé est restauré dans une équipe où votre bot est déjà installé.

Le code suivant montre un exemple d’événement de restauration de canal :

protected override async Task OnTeamsChannelRestoredAsync(ChannelInfo channelInfo, TeamInfo teamInfo, ITurnContext<IConversationUpdateActivity> turnContext, CancellationToken cancellationToken)
{
    var heroCard = new HeroCard(text: $"{channelInfo.Name} is the Channel restored.");
    await turnContext.SendActivityAsync(MessageFactory.Attachment(heroCard.ToAttachment()), cancellationToken);
}

Membres d’équipe ajoutés

L’événement est envoyé à votre bot la première fois qu’il est teamMemberAdded ajouté à une conversation. L’événement est envoyé à votre bot chaque fois qu’un nouvel utilisateur est ajouté à une conversation d’équipe ou de groupe où votre bot est installé. Les informations utilisateur qui sont des ID, sont uniques pour votre bot et peuvent être mises en cache pour une utilisation ultérieure par votre service, telles que l’envoi d’un message à un utilisateur spécifique.

Le code suivant montre un exemple d’événement ajouté aux membres de l’équipe :

protected override async Task OnTeamsMembersAddedAsync(IList<TeamsChannelAccount> teamsMembersAdded , TeamInfo teamInfo, ITurnContext<IConversationUpdateActivity> turnContext, CancellationToken cancellationToken)
{
    foreach (TeamsChannelAccount member in teamsMembersAdded)
    {
        if (member.Id == turnContext.Activity.Recipient.Id)
        {
            // Send a message to introduce the bot to the team
            var heroCard = new HeroCard(text: $"The {member.Name} bot has joined {teamInfo.Name}");
            await turnContext.SendActivityAsync(MessageFactory.Attachment(heroCard.ToAttachment()), cancellationToken);
        }
        else
        {
            var heroCard = new HeroCard(text: $"{member.Name} joined {teamInfo.Name}");
            await turnContext.SendActivityAsync(MessageFactory.Attachment(heroCard.ToAttachment()), cancellationToken);
        }
    }
}

Membres d’équipe supprimés

teamMemberRemovedL’événement est envoyé à votre bot s’il est supprimé d’une équipe. L’événement est envoyé à votre bot chaque fois qu’un utilisateur est supprimé d’une équipe dont il est membre. Pour déterminer si le nouveau membre supprimé était le bot lui-même ou un utilisateur, vérifiez Activity l’objet du turnContext . Si le champ de l’objet est identique au champ de l’objet, le membre supprimé est le bot, sinon il Id MembersRemoved Id s’agit Recipient d’un utilisateur. Le bot est Id généralement 28:<MicrosoftAppId> .

Notes

Lorsqu’un utilisateur est définitivement supprimé d’un client, membersRemoved conversationUpdate l’événement est déclenché.

Le code suivant montre un exemple d’événement supprimé des membres de l’équipe :

protected override async Task OnTeamsMembersRemovedAsync(IList<ChannelAccount> membersRemoved, TeamInfo teamInfo, ITurnContext<IConversationUpdateActivity> turnContext, CancellationToken cancellationToken)
{
    foreach (TeamsChannelAccount member in membersRemoved)
    {
        if (member.Id == turnContext.Activity.Recipient.Id)
        {
            // The bot was removed
            // You should clear any cached data you have for this team
        }
        else
        {
            var heroCard = new HeroCard(text: $"{member.Name} was removed from {teamInfo.Name}");
            await turnContext.SendActivityAsync(MessageFactory.Attachment(heroCard.ToAttachment()), cancellationToken);
        }
    }
}

Équipe renommée

Votre bot est averti lorsque l’équipe est renommée. Il reçoit un conversationUpdate événement avec eventType.teamRenamed dans channelData l’objet.

Le code suivant montre un exemple d’événement renommé d’équipe :

protected override async Task OnTeamsTeamRenamedAsync(TeamInfo teamInfo, ITurnContext<IConversationUpdateActivity> turnContext, CancellationToken cancellationToken)
{
    var heroCard = new HeroCard(text: $"{teamInfo.Name} is the new Team name");
    await turnContext.SendActivityAsync(MessageFactory.Attachment(heroCard.ToAttachment()), cancellationToken);
}

Équipe supprimée

Votre bot est averti lorsque l’équipe est supprimée. Il reçoit un conversationUpdate événement avec eventType.teamDeleted dans channelData l’objet.

Le code suivant illustre un exemple d’événement supprimé par l’équipe :

protected override async Task OnTeamsTeamDeletedAsync(TeamInfo teamInfo, ITurnContext<IConversationUpdateActivity> turnContext, CancellationToken cancellationToken)
{
    //handle delete event
}

Équipe restaurée

Le bot reçoit une notification lorsqu’une équipe est restaurée après avoir été supprimée. Il reçoit un conversationUpdate événement avec eventType.teamrestored dans channelData l’objet.

Le code suivant illustre un exemple d’événement restauré par l’équipe :

protected override async Task OnTeamsTeamrestoredAsync(TeamInfo teamInfo, ITurnContext<IConversationUpdateActivity> turnContext, CancellationToken cancellationToken)
{
    var heroCard = new HeroCard(text: $"{teamInfo.Name} is the team name");
    await turnContext.SendActivityAsync(MessageFactory.Attachment(heroCard.ToAttachment()), cancellationToken);
}

Équipe archivée

Le bot reçoit une notification lorsque l’équipe est installée et archivée. Il reçoit un conversationUpdate événement avec eventType.teamarchived dans channelData l’objet.

Le code suivant montre un exemple d’événement d’équipe archivé :

protected override async Task OnTeamsTeamArchivedAsync(TeamInfo teamInfo, ITurnContext<IConversationUpdateActivity> turnContext, CancellationToken cancellationToken)
{
    var heroCard = new HeroCard(text: $"{teamInfo.Name} is the team name");
    await turnContext.SendActivityAsync(MessageFactory.Attachment(heroCard.ToAttachment()), cancellationToken);
}

Équipe non archivée

Le bot reçoit une notification lorsque l’équipe est installée et désarchive. Il reçoit un conversationUpdate événement avec eventType.teamUnarchived dans channelData l’objet.

Le code suivant montre un exemple d’événement nonarchif d’équipe :

protected override async Task OnTeamsTeamUnarchivedAsync(TeamInfo teamInfo, ITurnContext<IConversationUpdateActivity> turnContext, CancellationToken cancellationToken)
{
    var heroCard = new HeroCard(text: $"{teamInfo.Name} is the team name");
    await turnContext.SendActivityAsync(MessageFactory.Attachment(heroCard.ToAttachment()), cancellationToken);
}

Maintenant que vous avez travaillé avec les événements de mise à jour de conversation, vous pouvez comprendre les événements de réaction de message qui se produisent pour différentes réactions à un message.

Événements de réaction aux messages

L’événement est envoyé lorsqu’un utilisateur ajoute ou supprime des réactions à un message envoyé messageReaction par votre bot. Contient l’ID du message et le type de réaction au replyToId Type format texte. Les types de réactions sont notamment les enfants, les cœurs, les enfants, les enfants, les enfants et les surprises. Cet événement ne contient pas le contenu du message d’origine. Si le traitement des réactions à vos messages est important pour votre bot, vous devez stocker les messages lorsque vous les envoyez. Le tableau suivant fournit plus d’informations sur le type d’événement et les objets de charge utile :

EventType Objet Payload Description Portée
messageReaction reactionsAdded Réactions ajoutées au message du bot. Tous
messageReaction reactionsRemoved Réactions supprimées du message du bot. Tous

Réactions ajoutées au message du bot

Le code suivant montre un exemple de réactions à un message de bot :

protected override async Task OnReactionsAddedAsync(IList<MessageReaction> messageReactions, ITurnContext<IMessageReactionActivity> turnContext, CancellationToken cancellationToken)
{
    foreach (var reaction in messageReactions)
    {
      var newReaction = $"You reacted with '{reaction.Type}' to the following message: '{turnContext.Activity.ReplyToId}'";
      var replyActivity = MessageFactory.Text(newReaction);
      var resourceResponse = await turnContext.SendActivityAsync(replyActivity, cancellationToken);
    }
}

Réactions supprimées du message du bot

Le code suivant montre un exemple de réactions supprimées du message du bot :

protected override async Task OnReactionsRemovedAsync(IList<MessageReaction> messageReactions, ITurnContext<IMessageReactionActivity> turnContext, CancellationToken cancellationToken)
{
    foreach (var reaction in messageReactions)
    {
      var newReaction = $"You removed the reaction '{reaction.Type}' from the following message: '{turnContext.Activity.ReplyToId}'";
      var replyActivity = MessageFactory.Text(newReaction);
      var resourceResponse = await turnContext.SendActivityAsync(replyActivity, cancellationToken);
    }
}

Événement de mise à jour d’installation

Le bot reçoit un installationUpdate événement lorsque vous installez un bot sur un thread de conversation. La désinstallation du bot du thread déclenche également l’événement. Lors de l’installation d’un bot, le champ d’action dans l’événement est définie pour ajouter , et lorsque le bot est désinstallé, le champ d’action est définie pour supprimer.

Notes

Lorsque vous mettre à niveau une application, puis ajoutez ou supprimez un bot, l’action déclenche également installationUpdate l’événement. Le champ d’action est définie sur add-upgrade si vous ajoutez un bot ou remove-upgrade si vous supprimez un bot.

Installer l’événement de mise à jour

Utilisez installationUpdate l’événement pour envoyer un message d’introduction à partir de votre bot lors de l’installation. Cet événement vous aide à répondre à vos exigences de confidentialité et de rétention des données. Vous pouvez également nettoyer et supprimer des données utilisateur ou thread lorsque le bot est désinstallé.

protected override async Task
OnInstallationUpdateActivityAsync(ITurnContext<IInstallationUpdateActivity> turnContext, CancellationToken cancellationToken) {
var activity = turnContext.Activity; if
(string.Equals(activity.Action, "Add",
StringComparison.InvariantCultureIgnoreCase)) {
// TO:DO Installation workflow }
else
{ // TO:DO Uninstallation workflow
} return; }

Vous pouvez également utiliser un handler dédié pour ajouter ou supprimer des scénarios en tant que méthode alternative pour capturer un événement.

protected override async Task
OnInstallationUpdateAddAsync(ITurnContext<IInstallationUpdateActivity>
turnContext, CancellationToken cancellationToken) {
// TO:DO Installation workflow return;
}

Comportement de désinstallation pour une application personnelle avec un bot

Notes

Le comportement de désinstallation pour une application personnelle avec un bot est actuellement disponible uniquement en prévisualisation pour les développeurs publics.

Lorsque vous désinstallez une application, le bot est également désinstallé. Lorsqu’un utilisateur envoie un message à votre application, il reçoit un code de réponse 403. Votre bot reçoit un code de réponse 403 pour les nouveaux messages publiés par votre bot. Le comportement de post-désinstallation pour les bots dans l’étendue personnelle avec les Teams et groupChat sont désormais alignés. Vous ne pouvez pas envoyer ou recevoir de messages après la désinstallation d’une application.

Uninstall event

Gestion des événements pour les événements d’installation et de désinstallation

Lorsque vous utilisez ces événements d’installation et de désinstallation, il existe certaines instances où les bots donnent des exceptions sur la réception d’événements inattendus de Teams. Cela se produit dans les cas suivants :

  • Vous créez votre bot sans le SDK Microsoft Bot Framework et, par conséquent, le bot fournit une exception sur la réception d’un événement inattendu.
  • Vous créez votre bot avec le SDK Microsoft Bot Framework, et vous choisissez de modifier le comportement des événements par défaut en remplacement du handle d’événement de base.

Il est important de savoir que de nouveaux événements peuvent être ajoutés à tout moment à l’avenir et que votre bot commence à les recevoir. Vous devez donc concevoir la possibilité de recevoir des événements inattendus. Si vous utilisez le SDK Bot Framework, votre bot répond automatiquement avec un 200 - OK pour tous les événements que vous ne choisissez pas de gérer.

Exemple de code

Exemple de nom Description .NET Node.js Python
Bot de conversation Exemple de code pour les événements de conversation de bots. View View View

Étape suivante