Nota:
El acceso a esta página requiere autorización. Puede intentar iniciar sesión o cambiar directorios.
El acceso a esta página requiere autorización. Puede intentar cambiar los directorios.
Al compilar los agentes de conversación para Microsoft Teams, puede trabajar con eventos de conversación. Teams envía notificaciones al agente para eventos de conversación que se producen en ámbitos donde el agente está activo. Puede capturar estos eventos en el código y tomar medidas como las siguientes:
- Desencadene un mensaje de bienvenida cuando el agente se agregue a un equipo.
- Desencadenar un mensaje de bienvenida cuando se añade o quita un nuevo miembro del equipo;
- Desencadenar una notificación cuando se crea, cambia el nombre o elimina un canal;
- Desencadena una notificación cuando un usuario le gusta un mensaje de agente.
- Identifique el canal predeterminado para el agente a partir de la entrada del usuario (selección) durante la instalación.
Eventos de actualización de conversación
Puede usar eventos de actualización de conversación para proporcionar mejores notificaciones y acciones eficaces del agente.
Importante
- Puede agregar nuevos eventos en cualquier momento y el agente comienza a recibirlos.
- Diseñe el agente para recibir eventos inesperados.
- Si usa el SDK de Teams, el agente responde automáticamente con un
200 - OKa los eventos que elija no controlar. - Cuando un cliente de Azure Communication Services (ACS) se une o deja la reunión de Teams, no se desencadena ningún evento de actualización de conversación.
Un agente recibe un conversationUpdate evento en cualquiera de los casos siguientes:
- Cuando el agente se agrega a una conversación.
- Otros miembros se agregan o quitan de una conversación.
- Los metadatos de conversación han cambiado.
El conversationUpdate evento se envía al agente cuando recibe información sobre las actualizaciones de pertenencia de los equipos en los que se ha agregado. También recibe una actualización cuando se ha agregado por primera vez, específicamente para conversaciones personales.
En la tabla siguiente se muestra una lista de los eventos de conversación actualizados de Teams 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 elimina un miembro. | todas |
| 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 | Se desarchiva un equipo. | Equipo |
| Equipo restaurado | teamRestored | OnTeamsTeamRestoredAsync | Se restaura un equipo | Equipo |
Canal creado
El channelCreated evento se envía al agente cada vez que se crea un nuevo canal en un equipo donde está instalado el agente.
El código siguiente muestra un ejemplo de un evento creado por un canal:
app.OnChannelCreated(async context =>
{
var channelName = context.Activity.ChannelData.Channel.Name;
await context.Send($"{channelName} is the Channel created");
});
Se cambió el nombre del canal
El channelRenamed evento se envía al agente cada vez que se cambia el nombre de un canal en un equipo donde está instalado el agente.
En el código siguiente se muestra un ejemplo de un evento con el nombre cambiado de canal:
app.OnChannelRenamed(async context =>
{
var channelName = context.Activity.ChannelData.Channel.Name;
await context.Send($"{channelName} is the new Channel name");
});
Canal eliminado
El channelDeleted evento se envía al agente cada vez que se elimina un canal en un equipo donde está instalado el agente.
El código siguiente muestra un ejemplo de un evento eliminado de canal:
app.OnChannelDeleted(async context =>
{
var channelName = context.Activity.ChannelData.Channel.Name;
await context.Send($"{channelName} is the Channel deleted");
});
Canal restaurado
El channelRestored evento se envía al agente siempre que se restaure un canal que se eliminó anteriormente en un equipo donde el agente ya está instalado.
El código siguiente muestra un ejemplo de un evento restaurado de canal:
app.OnChannelRestored(async context =>
{
var channelName = context.Activity.ChannelData.Channel.Name;
await context.Send($"{channelName} is the Channel restored.");
});
Miembros agregados
Se envía un evento agregado de miembro al agente en los siguientes escenarios:
Cuando el agente, en sí mismo, se instala y se agrega a una conversación
En el contexto del equipo, el conversation.id de la actividad se establece en el
iddel canal seleccionado por el usuario durante la instalación de la aplicación o en el canal donde se instaló el agente.Cuando se agrega un usuario a una conversación en la que está instalado el agente
Los identificadores de usuario recibidos en la carga del evento son únicos para el agente y se pueden almacenar en caché para su uso futuro, como la mensajería directa de un usuario.
La actividad eventType agregada de miembro se establece en teamMemberAdded cuando el evento se envía desde un contexto de equipo. Para determinar si el nuevo miembro agregado era el propio agente o un usuario, compruebe el Activity objeto de Context object. Si la MembersAdded lista contiene un objeto donde id es el mismo que el id campo del Recipient objeto, el miembro agregado es el agente; de lo contrario, es un usuario. El del agente id tiene el formato 28:<MicrosoftAppId>.
Sugerencia
Use el InstallationUpdate evento para determinar cuándo se agrega o quita el agente de una conversación.
En el código siguiente se muestra un ejemplo de un evento agregado por miembros del equipo:
app.OnMembersAdded(async context =>
{
foreach (var member in context.Activity.MembersAdded)
{
if (member.Id == context.Activity.Recipient.Id)
{
// Send a message to introduce the bot to the team.
await context.Send($"The {member.Name} agent has joined {context.Activity.ChannelData.Team.Name}");
}
else
{
await context.Send($"{member.Name} joined {context.Activity.ChannelData.Team.Name}");
}
}
});
Miembros eliminados
Un evento quitado de miembro se envía al agente en los siguientes escenarios:
- Cuando el agente, en sí mismo, se desinstala y quita de una conversación.
- Cuando se quita un usuario de una conversación en la que está instalado el agente.
La actividad eventType quitada de miembro se establece en teamMemberRemoved cuando el evento se envía desde un contexto de equipo. Para determinar si el nuevo miembro quitado era el propio agente o un usuario, compruebe el Activity objeto de Context object. Si la MembersRemoved lista contiene un objeto donde id es el mismo que el id campo del Recipient objeto, el miembro agregado es el agente; de lo contrario, es un usuario. El identificador del agente tiene el formato 28:<MicrosoftAppId>.
Nota:
Cuando un usuario se elimina permanentemente de un inquilino, se desencadena el evento membersRemoved conversationUpdate.
En el código siguiente se muestra un ejemplo de un evento quitado de miembros del equipo:
app.OnMembersRemoved(async context =>
{
foreach (var member in context.Activity.MembersRemoved)
{
if (member.Id == context.Activity.Recipient.Id)
{
// The agent was removed.
// You should clear any cached data you have for this team.
}
else
{
await context.Send($"{member.Name} was removed from {context.Activity.ChannelData.Team.Name}");
}
}
});
Se cambió el nombre del equipo
Se notifica al agente cuando se cambia el nombre del equipo. Recibe un evento conversationUpdate con eventType.teamRenamed en el objeto channelData.
En el código siguiente se muestra un ejemplo de un evento cuyo nombre ha cambiado el equipo:
app.OnTeamRenamed(async context =>
{
var teamName = context.Activity.ChannelData.Team.Name;
await context.Send($"{teamName} is the new Team name");
});
Equipo eliminado
El agente recibe una notificación cuando se elimina el equipo. Recibe un evento conversationUpdate con eventType.teamDeleted en el objeto channelData.
El código siguiente muestra un ejemplo de un evento eliminado por el equipo:
app.OnTeamDeleted(async context =>
{
// Handle delete event.
});
Equipo restaurado
El agente recibe una notificación cuando se restaura un equipo después de eliminarse. Recibe un evento conversationUpdate con eventType.teamrestored en el objeto channelData.
En el código siguiente se muestra un ejemplo de un evento restaurado por el equipo:
app.OnTeamRestored(async context =>
{
var teamName = context.Activity.ChannelData.Team.Name;
await context.Send($"{teamName} is the team name");
});
Equipo archivado
El agente recibe una notificación cuando el equipo está instalado y archivado. Recibe un evento conversationUpdate con eventType.teamarchived en el objeto channelData.
En el código siguiente se muestra un ejemplo de evento archivado por el equipo:
app.OnTeamArchived(async context =>
{
var teamName = context.Activity.ChannelData.Team.Name;
await context.Send($"{teamName} is the team name");
});
Equipo desarchivado
El agente recibe una notificación cuando el equipo está instalado y desarchivo. Recibe un evento conversationUpdate con eventType.teamUnarchived en el objeto channelData.
En el código siguiente se muestra un ejemplo de un evento noarchivo de equipo:
app.OnTeamUnarchived(async context =>
{
var teamName = context.Activity.ChannelData.Team.Name;
await context.Send($"{teamName} is the team name");
});
Ahora que ha trabajado con los eventos de actualización de conversación, puede comprender los eventos de reacción del mensaje que se producen para diferentes reacciones a un mensaje.
Eventos de reacción de mensajes
El messageReaction evento se envía cuando un usuario agrega o quita las reacciones a un mensaje que envió el agente.
replyToId contiene el identificador del mensaje y Type es el tipo de reacción en formato de texto. Los tipos de reacciones incluyen enfado, corazón, risa, me gusta, triste y sorprendido. Este evento no contiene el contenido del mensaje original. Si el procesamiento de reacciones a los mensajes es importante para el agente, debe almacenar los mensajes cuando los envíe. En la tabla siguiente se proporciona más información sobre el tipo de evento y los objetos de carga:
| EventType | Objeto de carga | Descripción | Ámbito |
|---|---|---|---|
| messageReaction | reactionsAdded | Reacciones agregadas al mensaje del agente. | Todo |
| messageReaction | reactionsRemoved | Reacciones eliminadas del mensaje del agente. | todas |
Reacciones agregadas al mensaje del agente
En el código siguiente se muestra un ejemplo de reacciones a un mensaje de agente:
app.OnReactionsAdded(async context =>
{
foreach (var reaction in context.Activity.ReactionsAdded)
{
var newReaction = $"You reacted with '{reaction.Type}' to the following message: '{context.Activity.ReplyToId}'";
await context.Send(newReaction);
}
});
Reacciones eliminadas del mensaje del agente
En el código siguiente se muestra un ejemplo de reacciones eliminadas del mensaje del agente:
app.OnReactionsRemoved(async context =>
{
foreach (var reaction in context.Activity.ReactionsRemoved)
{
var newReaction = $"You removed the reaction '{reaction.Type}' from the following message: '{context.Activity.ReplyToId}'";
await context.Send(newReaction);
}
});
Evento de actualización de instalación
El agente recibe un installationUpdate evento al instalar un agente en un subproceso de conversación. La desinstalación del agente desde el subproceso también desencadena el evento. Al instalar un agente, el campo de acción del evento se establece en agregar y, cuando se desinstala el agente, el campo de acción se establece en quitar.
Nota:
Al actualizar una aplicación, el agente recibe el installationUpdate evento solo para agregar o quitar un agente del manifiesto. En todos los demás casos, el installationUpdate evento no se desencadena. El campo de acción se establece en add-upgrade si agrega un agente o remove-upgrade si quita un agente.
Instalar evento de actualización
Use el installationUpdate evento para enviar un mensaje de introducción desde el agente durante la instalación. Este evento le ayuda a cumplir sus requisitos de privacidad y retención de datos. También puede limpiar y eliminar datos de usuario o subproceso cuando se desinstala el agente.
De forma similar al conversationUpdate evento que se envía cuando se agrega el agente a un equipo, el conversation.id del installationUpdate evento se establece en el identificador del canal seleccionado por un usuario durante la instalación de la aplicación o en el canal donde se produjo la instalación. El identificador representa el canal donde el usuario pretende que el agente funcione y el agente debe usarlo al enviar un mensaje de bienvenida. Para escenarios en los que se requiere explícitamente el identificador del canal General, puede obtenerlo desde team.id en channelData.
En este ejemplo, el conversation.id de las conversationUpdate actividades y installationUpdate se establece en el identificador del canal de respuesta en el equipo de demostración de Daves.
Nota:
El identificador de canal seleccionado solo se establece en agregarinstallationUpdate eventos que se envían cuando se instala una aplicación en un equipo.
app.OnInstall(async context =>
{
var action = context.Activity.Action;
if (string.Equals(action, "Add", StringComparison.InvariantCultureIgnoreCase))
{
await context.Send("Added");
}
else
{
await context.Send("Uninstalled");
}
});
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(IContext<IInstallationUpdateActivity> Context object, CancellationToken cancellationToken)
{
// TO:DO Installation workflow return;
}
Comportamiento de desinstalación de una aplicación personal con el agente
Al desinstalar una aplicación, también se desinstala el agente. Cuando un usuario envía un mensaje a la aplicación, recibe un código de respuesta 403. El agente recibe un código de respuesta 403 para los nuevos mensajes publicados por el agente. El comportamiento posterior a la desinstalación de los agentes en el ámbito personal con los ámbitos teams y groupChat ahora está alineado. No puede enviar ni recibir mensajes después de desinstalar una aplicación.
Control de eventos para eventos de instalación y desinstalación
Cuando se usan los eventos de instalación y desinstalación, hay algunas instancias en las que los agentes dan excepciones en la recepción de eventos inesperados de Teams, lo que se produce en los casos siguientes:
- El agente se compila sin el SDK de Teams y, como resultado, el agente proporciona una excepción al recibir un evento inesperado.
- Compile el agente con el SDK de Teams y seleccione modificar el comportamiento predeterminado del evento reemplazando el identificador de eventos base.
Es importante saber que los nuevos eventos se pueden agregar en cualquier momento en el futuro y que el agente comienza a recibirlos. Por lo tanto, debe diseñar para la posibilidad de recibir eventos inesperados. Si usa el SDK de Teams, el agente responde automáticamente con un 200 - OK a los eventos que no elija controlar.
Control de errores en eventos de conversación
Cuando un agente encuentra un error al controlar diferentes eventos o actividades, no envíe mensajes que no tengan ningún contexto significativo a la conversación, como se muestra en la captura de pantalla siguiente:
En la fase de desarrollo, siempre resulta útil enviar mensajes significativos en las conversaciones, lo que proporciona detalles adicionales sobre un error específico para una mejor depuración. Sin embargo, en el entorno de producción, debe registrar los errores o eventos en Aplicación de Azure Insights. Para obtener más información, consulte Adición de telemetría al bot.
Ejemplo de código
| Nombre de ejemplo | Descripción | .NET | Node.js | Python |
|---|---|---|---|---|
| Bot conversacional | Esta aplicación muestra los eventos de conversación del bot, las tarjetas adaptables, los recibos de lectura y los eventos de actualización de mensajes. Incluye compatibilidad con lector inmersivo para la accesibilidad. | View | View | View |
Paso siguiente
Colaborar con nosotros en GitHub
El origen de este contenido se puede encontrar en GitHub, donde también puede crear y revisar problemas y solicitudes de incorporación de cambios. Para más información, consulte nuestra guía para colaboradores.