Eventos de conversación en el bot de Teams

Importante

Los ejemplos de código de esta sección se basan en la versión 4.6 y versiones posteriores del SDK de Bot Framework. Si está buscando documentación para versiones anteriores, consulte la sección bots - v3 SDK en la carpeta Resources de la documentación.

Al crear los bots de conversación para Microsoft Teams, puede trabajar con eventos de conversación. Teams envía notificaciones al bot para eventos de conversación que se suceden en ámbitos donde el bot está activo. Puede capturar estos eventos en el código y realizar las siguientes acciones:

  • Desencadena un mensaje de bienvenida cuando el bot se agrega a un equipo.
  • Desencadena un mensaje de bienvenida cuando se agrega o quita un nuevo miembro del equipo.
  • Desencadena una notificación cuando se crea, cambia el nombre o elimina un canal.
  • Cuando un usuario le gusta un mensaje de bot.

Eventos de actualización de conversación

Puedes usar eventos de actualización de conversación para proporcionar mejores notificaciones y acciones de bot más eficaces.

Importante

  • Puedes agregar eventos nuevos en cualquier momento y el bot comienza a recibirlos.
  • Debe diseñar el bot para recibir eventos inesperados.
  • Si usa el SDK de Bot Framework, el bot responde automáticamente con un a a los eventos 200 - OK que decida no controlar.

Un bot recibe un conversationUpdate evento en cualquiera de los siguientes casos:

  • Cuando el bot se ha agregado a una conversación.
  • Otros miembros se agregan o quitan de una conversación.
  • Los metadatos de conversación han cambiado.

El evento conversationUpdate se envía al bot cuando recibe información sobre las actualizaciones de suscripción de los equipos donde se ha agregado. También recibe una actualización cuando se ha agregado por primera vez para conversaciones personales.

En la tabla siguiente se muestra una lista de Teams eventos de actualización de conversación con más detalles:

Acción realizada EventType Método llamado Descripción Ámbito
Canal creado channelCreated OnTeamsChannelCreatedAsync Se crea un canal. Equipo
Se cambió el nombre del canal channelRenamed OnTeamsChannelRenamedAsync Se cambia el nombre de un canal. Equipo
Canal eliminado channelDeleted OnTeamsChannelDeletedAsync Se elimina un canal. Equipo
Canal restaurado channelRestored OnTeamsChannelRestoredAsync Se restaura un canal. Equipo
Miembros agregados membersAdded OnTeamsMembersAddedAsync Se agrega un miembro. Todo
Miembros eliminados membersRemoved OnTeamsMembersRemovedAsync Se quita un miembro. groupChat y equipo
Se cambió el nombre del equipo teamRenamed OnTeamsTeamRenamedAsync Se cambia el nombre de un equipo. Equipo
Equipo eliminado teamDeleted OnTeamsTeamDeletedAsync Se elimina un equipo. Equipo
Equipo archivado teamArchived OnTeamsTeamArchivedAsync Se archiva un equipo. Equipo
Equipo desarchivado teamUnarchived OnTeamsTeamUnarchivedAsync Un equipo no está anárquico. Equipo
Equipo restaurado teamRestored OnTeamsTeamRestoredAsync Se restaura un equipo Equipo

Canal creado

El evento de canal creado se envía al bot cada vez que se crea un nuevo canal en un equipo donde está instalado el bot.

El siguiente código muestra un ejemplo de evento creado por el canal:

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

Se cambió el nombre del canal

El evento de cambio de nombre de canal se envía al bot siempre que se cambie el nombre de un canal en un equipo donde esté instalado el bot.

El siguiente código muestra un ejemplo de evento con el nombre 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 eliminado

El evento de eliminación de canal se envía al bot, siempre que se elimine un canal en un equipo donde esté instalado el bot.

El siguiente código muestra un ejemplo de evento eliminado del 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 restaurado

El evento restaurado del canal se envía al bot, siempre que se restaure un canal que se eliminó anteriormente en un equipo en el que el bot ya está instalado.

El código siguiente muestra un ejemplo de evento restaurado del 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);
}

Miembros del equipo agregados

El evento se envía al bot la primera vez que se teamMemberAdded agrega a una conversación. El evento se envía al bot cada vez que se agrega un nuevo usuario a un chat de grupo o equipo donde está instalado el bot. La información del usuario que es id., es única para el bot y puede almacenarse en caché para su uso futuro por el servicio, como enviar un mensaje a un usuario específico.

El código siguiente muestra un ejemplo de evento agregado por los miembros del equipo:

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

Miembros del equipo eliminados

El teamMemberRemoved evento se envía al bot si se quita de un equipo. El evento se envía al bot cada vez que se quita cualquier usuario de un equipo en el que el bot es miembro. Para determinar si el nuevo miembro quitado era el propio bot o un usuario, compruebe el Activity objeto de turnContext . Si el campo del objeto es el mismo que el campo del objeto, el miembro quitado es el bot, de lo contrario Id MembersRemoved es un Id Recipient usuario. Por lo general, el bot Id es 28:<MicrosoftAppId> .

Nota

Cuando un usuario se elimina permanentemente de un inquilino, membersRemoved conversationUpdate se desencadena el evento.

El código siguiente muestra un ejemplo de evento de miembros del equipo eliminados:

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

Se cambió el nombre del equipo

El bot se notifica cuando se cambia el nombre del equipo. Recibe un conversationUpdate evento con en el eventType.teamRenamed channelData objeto.

El siguiente código muestra un ejemplo de evento con el nombre de equipo:

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

Equipo eliminado

El bot se notifica cuando se elimina el equipo. Recibe un conversationUpdate evento con en el eventType.teamDeleted channelData objeto.

El código siguiente muestra un ejemplo de evento eliminado por el equipo:

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

Equipo restaurado

El bot recibe una notificación cuando se restaura un equipo después de eliminarse. Recibe un conversationUpdate evento con en el eventType.teamrestored channelData objeto.

El código siguiente muestra un ejemplo de evento restaurado por el equipo:

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

Equipo archivado

El bot recibe una notificación cuando el equipo está instalado y archivado. Recibe un conversationUpdate evento con en el eventType.teamarchived channelData objeto.

El siguiente código muestra un ejemplo de evento archivado por el equipo:

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

Equipo desarchivado

El bot recibe una notificación cuando el equipo está instalado y sin jerarquía. Recibe un conversationUpdate evento con en el eventType.teamUnarchived channelData objeto.

En el código siguiente se muestra un ejemplo de evento de equipo no anárquico:

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

Ahora que ha trabajado con los eventos de actualización de conversación, puede comprender los eventos de reacción de mensajes que se producen para diferentes reacciones a un mensaje.

Eventos de reacción de mensajes

El evento se envía cuando un usuario agrega o quita las reacciones a un mensaje enviado messageReaction por el bot. Contiene el identificador del mensaje y es el tipo replyToId de reacción en formato de Type texto. Los tipos de reacciones incluyen el enojo, el corazón, la carcajada, como, la tristeza y la sorpresa. Este evento no contiene el contenido del mensaje original. Si el procesamiento de las reacciones a los mensajes es importante para el bot, debe almacenar los mensajes al enviarlos. En la tabla siguiente se proporciona más información sobre el tipo de evento y los objetos de carga:

EventType Payload (objeto) Descripción Ámbito
messageReaction reactionsAdded Reacciones agregadas al mensaje de bot. Todo
messageReaction reactionsRemoved Reacciones eliminadas del mensaje de bot. Todo

Reacciones agregadas al mensaje de bot

El código siguiente muestra un ejemplo de las reacciones a un mensaje 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);
    }
}

Reacciones eliminadas del mensaje de bot

El siguiente código muestra un ejemplo de las reacciones eliminadas del mensaje del 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);
    }
}

Evento de actualización de instalación

El bot recibe un installationUpdate evento al instalar un bot en un subproceso de conversación. La desinstalación del bot del subproceso también desencadena el evento. Al instalar un bot, el campo de acción del evento se establece en agregar y, cuando se desinstala el bot, el campo de acción se establece en quitar.

Nota

Al actualizar una aplicación y, a continuación, agregar o quitar un bot, la acción también desencadena el installationUpdate evento. El campo de acción se establece en add-upgrade si agrega un bot o remove-upgrade si quita un bot.

Evento Install update

Use el installationUpdate evento para enviar un mensaje introductorio desde el bot durante la instalación. Este evento le ayuda a cumplir los requisitos de privacidad y retención de datos. También puede limpiar y eliminar datos de usuario o subproceso cuando se desinstala el bot.

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; }

También puede usar un controlador dedicado para agregar o quitar escenarios como método alternativo para capturar un evento.

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

Comportamiento de desinstalación de la aplicación personal con bot

Nota

El comportamiento de desinstalación de la aplicación personal con bot solo está disponible actualmente en la versión preliminar del desarrollador público.

Al desinstalar una aplicación, el bot también se desinstala. Cuando un usuario envía un mensaje a la aplicación, recibe un código de respuesta 403. El bot recibe un código de respuesta 403 para los nuevos mensajes publicados por el bot. El comportamiento posterior a la desinstalación de bots en el ámbito personal con los ámbitos Teams y groupChat ahora están alineados. No puedes enviar ni recibir mensajes después de desinstalar una aplicación.

Uninstall event

Control de eventos para eventos de instalación y desinstalación

Al usar estos eventos de instalación y desinstalación, hay algunas instancias en las que los bots dan excepciones al recibir eventos inesperados de Teams. Esto ocurre en los siguientes casos:

  • Creas el bot sin el SDK Microsoft Bot Framework y, como resultado, el bot da una excepción al recibir un evento inesperado.
  • Creas el bot con el SDK de Microsoft Bot Framework y seleccionas modificar el comportamiento de evento predeterminado invalidando el identificador de evento base.

Es importante saber que los nuevos eventos se pueden agregar en cualquier momento en el futuro y el bot comienza a recibirlos. Por lo tanto, debe diseñar la posibilidad de recibir eventos inesperados. Si usa el SDK de Bot Framework, el bot responde automáticamente con un 200: aceptar cualquier evento que no elija controlar.

Ejemplo de código

Ejemplo de nombre Descripción .NET Node.js Python
Bot de conversación Código de ejemplo para eventos de conversación de bots. View View View

Paso siguiente