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:
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:
async def on_teams_channel_restored(
self, channel_info: ChannelInfo, team_info: TeamInfo, turn_context: TurnContext
):
return await turn_context.send_activity(
MessageFactory.text(
f"The restored channel is {channel_info.name}. The channel id is {channel_info.id}"
)
)
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);
}
}
}
async def on_teams_members_added(
self, teams_members_added: [TeamsChannelAccount], turn_context: TurnContext
):
for member in teams_members_added:
await turn_context.send_activity(
MessageFactory.text(f"Welcome your new team member {member.id}")
)
return
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 IdMembersRemoved es un IdRecipient 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);
}
}
}
El objeto del siguiente ejemplo de carga se basa en agregar un miembro a un equipo en lugar de un chat de grupo o iniciar una nueva conversación uno channelData a uno:
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);
}
export class MyBot extends TeamsActivityHandler {
constructor() {
super();
this.onTeamsTeamRenamedEvent(async (teamInfo: TeamInfo, turnContext: TurnContext, next: () => Promise<void>): Promise<void> => {
const card = CardFactory.heroCard('Team Renamed', `${teamInfo.name} is the new Team name`);
const message = MessageFactory.attachment(card);
await turnContext.sendActivity(message);
await next();
});
}
}
async def on_teams_team_renamed(
self, team_info: TeamInfo, turn_context: TurnContext
):
return await turn_context.send_activity(
MessageFactory.text(f"The new team name is {team_info.name}")
)
Equipo eliminado
El bot se notifica cuando se elimina el equipo. Recibe un conversationUpdate evento con en el eventType.teamDeletedchannelData objeto.
El código siguiente muestra un ejemplo de evento eliminado por el equipo:
El bot recibe una notificación cuando se restaura un equipo después de eliminarse. Recibe un conversationUpdate evento con en el eventType.teamrestoredchannelData 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);
}
async def on_teams_team_restored(
self, team_info: TeamInfo, turn_context: TurnContext
):
return await turn_context.send_activity(
MessageFactory.text(f"The team name is {team_info.name}")
)
Equipo archivado
El bot recibe una notificación cuando el equipo está instalado y archivado. Recibe un conversationUpdate evento con en el eventType.teamarchivedchannelData 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);
}
async def on_teams_team_archived(
self, team_info: TeamInfo, turn_context: TurnContext
):
return await turn_context.send_activity(
MessageFactory.text(f"The team name is {team_info.name}")
)
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.teamUnarchivedchannelData 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);
}
async def on_teams_team_unarchived(
self, team_info: TeamInfo, turn_context: TurnContext
):
return await turn_context.send_activity(
MessageFactory.text(f"The team name is {team_info.name}")
)
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:
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);
}
}
export class MyBot extends TeamsActivityHandler {
constructor() {
super();
this.onReactionsAdded(async (context, next) => {
const reactionsAdded = context.activity.reactionsAdded;
if (reactionsAdded && reactionsAdded.length > 0) {
for (let i = 0; i < reactionsAdded.length; i++) {
const reaction = reactionsAdded[i];
const newReaction = `You reacted with '${reaction.type}' to the following message: '${context.activity.replyToId}'`;
const resourceResponse = context.sendActivity(newReaction);
// Save information about the sent message and its ID (resourceResponse.id).
}
}
});
}
}
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);
}
}
export class MyBot extends TeamsActivityHandler {
constructor() {
super();
this.onReactionsRemoved(async(context,next)=>{
const reactionsRemoved = context.activity.reactionsRemoved;
if (reactionsRemoved && reactionsRemoved.length > 0) {
for (let i = 0; i < reactionsRemoved.length; i++) {
const reaction = reactionsRemoved[i];
const newReaction = `You removed the reaction '${reaction.type}' from the message: '${context.activity.replyToId}'`;
const resourceResponse = context.sendActivity(newReaction);
// Save information about the sent message and its ID (resourceResponse.id).
}
}
});
}
}
async def on_reactions_removed(
self, message_reactions: List[MessageReaction], turn_context: TurnContext
):
for reaction in message_reactions:
activity = await self._log.find(turn_context.activity.reply_to_id)
if not activity:
await self._send_message_and_log_activity_id(
turn_context,
f"Activity {turn_context.activity.reply_to_id} not found in log",
)
else:
await self._send_message_and_log_activity_id(
turn_context,
f"You removed '{reaction.type}' regarding '{activity.text}'",
)
return
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.
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.
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.
