Cómo funcionan los bots de Microsoft Teams

SE APLICA A: SDK v4

Este artículo se basa en lo que ha aprendido en Cómo funcionan los bots y Conversaciones basadas en eventos; debe estar familiarizado con estos artículos antes de continuar.

La principal diferencia en los bots desarrollados para Microsoft Teams se encuentra en la forma en que se controlan las actividades. El controlador de actividad de Teams deriva del controlador de actividad y procesa los tipos de actividad específicos de Teams antes de procesar tipos de actividad más generales.

Nota:

Los SDK de JavaScript, C# y Python de Bot Framework seguirán siendo compatibles, pero el SDK de Java se va a retirar con la compatibilidad final a largo plazo que finaliza en noviembre de 2023.

Los bots existentes creados con el SDK de Java seguirán funcionando.

Para la nueva compilación de bots, considere la posibilidad de usar Microsoft Copilot Studio y lea sobre cómo elegir la solución de copilot adecuada.

Para obtener más información, consulte El futuro de la creación de bots.

Controlador de actividades de Teams

Para crear un bot para Teams, derive el bot de la clase de controlador de actividad de Teams. Cuando este bot recibe una actividad, enruta la actividad a través de varios controladores de actividad. El controlador base inicial es el controlador de turnos y enruta la actividad a un controlador en función del tipo de la actividad. El controlador de turnos llama al controlador que está diseñado para controlar el tipo específico de actividad que se recibió. La clase de controlador de actividad de Teams se deriva de la clase de controlador de actividad. Además de los tipos de actividad que el controlador de actividad puede procesar, la clase de controlador de actividad de Teams incluye controladores adicionales para actividades específicas de Teams.

Un bot que deriva del controlador de actividad de Teams es similar a un bot que deriva directamente de la clase del controlador de actividad. Sin embargo, Teams incluye información adicional en las actividades conversationUpdate y envía actividades invoke y event específicas de Teams.

C#

Cuando el controlador de actividad de Teams recibe una actividad de mensaje, su controlador de turnos enruta la actividad de mensaje entrante a su controlador OnMessageActivityAsync, similar a cómo lo haría un bot basado en controlador de actividad. Sin embargo, cuando el bot de Teams recibe una actividad de actualización de conversación, la versión de Teams del controlador OnConversationUpdateActivityAsync procesa la actividad.

No hay ninguna implementación base para la mayoría de los controladores de actividades específicos de Teams. Deberá invalidar estos controladores y proporcionar la lógica adecuada para el bot.

JavaScript

Cuando el controlador de actividad de Teams recibe una actividad de mensaje, su controlador de turnos enruta la actividad de mensaje entrante a su controlador onMessage, similar a cómo lo haría un bot basado en controlador de actividad. Sin embargo, cuando el bot de Teams recibe una actividad de actualización de conversación, la versión de Teams del controlador dispatchConversationUpdateActivity procesa la actividad.

No hay ninguna implementación base para la mayoría de los controladores de actividades específicos de Teams. Deberá invalidar estos controladores y proporcionar la lógica adecuada para el bot.

Defina la lógica del bot para cada uno de estos controladores de actividades específicos de Teams al invalidarlos y, después, no olvide llamar a next() al final. Al llamar a next(), asegúrese de que se ejecuta el siguiente controlador.

Java

Cuando el controlador de actividad de Teams recibe una actividad de mensaje, su controlador de turnos enruta la actividad de mensaje entrante a su controlador onMessageActivity, similar a cómo lo haría un bot basado en controlador de actividad. Sin embargo, cuando el bot de Teams recibe una actividad de actualización de conversación, la versión de Teams del controlador onConversationUpdateActivity procesa la actividad.

No hay ninguna implementación base para la mayoría de los controladores de actividades específicos de Teams. Deberá invalidar estos controladores y proporcionar la lógica adecuada para el bot.

Python

Cuando el controlador de actividad de Teams recibe una actividad de mensaje, su controlador de turnos enruta la actividad de mensaje entrante a su controlador on_message_activity, similar a cómo lo haría un bot basado en controlador de actividad. Sin embargo, cuando el bot de Teams recibe una actividad de actualización de conversación, la versión de Teams del controlador on_conversation_update_activity procesa la actividad.

No hay ninguna implementación base para la mayoría de los controladores de actividades específicos de Teams. Deberá invalidar estos controladores y proporcionar la lógica adecuada para el bot.

Todos los controladores de actividades que se describen en la sección control de actividades del artículo Conversaciones impulsadas por eventos usando un controlador de actividad seguirán funcionando como lo hacen con un bot que no es de Teams, con la excepción de controlar los miembros agregados y las actividades eliminadas, estas serán diferentes en el contexto de un equipo, donde el nuevo miembro se agrega al equipo en lugar de a un subproceso de mensaje. Para obtener más información, vea Actividades de actualización de conversaciones de Teams.

Para implementar tu lógica para estos controladores de actividad específicos de Teams, anulará métodos en el bot.

Lógica del bot de Teams

La lógica del bot procesa las actividades entrantes de uno o varios canales de los bots y genera actividades salientes como respuesta. Esto sigue siendo verdad en un bot derivado de la clase del controlador de actividades de Teams, que primero comprueba las actividades de Teams y, a continuación, pasa todas las demás actividades al controlador de actividades de Bot Framework.

Actividades de actualización de instalación de Teams

Agregue un controlador para el evento de actualización de instalación para permitir que el bot:

• Envíe un mensaje introductorio cuando esté instalado en un subproceso de conversación.
• Limpie los datos de usuario y subproceso cuando se desinstale de un subproceso.

Consulte Evento de actualización de instalación en los documentos de Teams para obtener más información.

Actividades de actualización de conversación de Teams

En la tabla siguiente se enumeran los eventos de Teams que generan una actividad de actualización de conversación en un bot. En el artículo Eventos de actualización de conversación de Microsoft Teams se describe cómo usar cada uno de estos eventos.

C#

A continuación se muestra una lista de todos los controladores de actividades de Teams a los que se llama desde el método OnConversationUpdateActivityAsync del controlador de actividades de Teams.

EventType	Handler	Condición	Documentación de Teams
channelCreated	OnTeamsChannelCreatedAsync	Se envía cada vez que se crea un nuevo canal en un equipo en el que se instala el bot.	Canal creado.
channelDeleted	OnTeamsChannelDeletedAsync	Se envía cada vez que se elimina un canal en un equipo en el que está instalado el bot.	Canal eliminado.
channelRenamed	OnTeamsChannelRenamedAsync	Se envía cada vez que se cambia el nombre de un canal en un equipo en el que está instalado el bot.	Se ha cambiado el nombre del canal.
channelRestored	OnTeamsChannelRestoredAsync	Se envía cada vez que se restaura un canal que se eliminó anteriormente en un equipo en el que el bot ya está instalado.	Canal restaurado.
membersAdded	OnTeamsMembersAddedAsync	De forma predeterminada, llama al método ActivityHandler.OnMembersAddedAsync. Se envía la primera vez que el bot se agrega a una conversación y cada vez que se agrega un nuevo usuario a un chat de grupo o equipo en el que está instalado el bot.	Se han agregado miembros del equipo.
membersRemoved	OnTeamsMembersRemovedAsync	De forma predeterminada, llama al método ActivityHandler.OnMembersRemovedAsync. Se envía si el bot se quita de un equipo y cada vez que se quita cualquier usuario de un equipo del que el bot es miembro.	Se han quitado miembros del equipo.
teamArchived	OnTeamsTeamArchivedAsync	Se envía cuando se archiva el equipo en el que está instalado el bot.	Equipo archivado.
teamDeleted	OnTeamsTeamDeletedAsync	Se envía cuando se ha eliminado el equipo en el que se encuentra el bot.	Equipo eliminado.
teamRenamed	OnTeamsTeamRenamedAsync	Se envía cuando se ha cambiado el nombre del equipo en el que se encuentra el bot.	Se ha cambiado el nombre del equipo.
teamRestored	OnTeamsTeamRestoredAsync	Se envía cuando se restaura un equipo eliminado previamente en el que se encuentra el bot.	Equipo restaurado.
teamUnarchived	OnTeamsTeamUnarchivedAsync	Se envía cuando el equipo en el que está instalado el bot no está archivado.	Equipo no archivado.

JavaScript

Los desarrolladores pueden controlar las actividades de actualización de conversación enviadas desde Microsoft Teams a través de dos métodos:

1. Para pasar una devolución de llamada, use métodos que comiencen por on y terminen con Event (por ejemplo, el onTeamsMembersAddedEvent método ).
2. Al crear una clase derivada, invalide los métodos que comienzan por on y no terminan con Event (por ejemplo, el método onTeamsMembersAdded).

Los desarrolladores deben usar solo una de estas opciones: 1 o 2, y no ambas para la misma actividad. Es decir, los desarrolladores deben pasar una devolución de llamada al método onTeamsMembersAddedEvent o invalidar el método onTeamsMembersAdded en una clase derivada y no ambos.

Métodos para registrar una devolución de llamada

A continuación se muestra una lista de todos los emisores de actividades de Teams a los que se llama desde el método dispatchConversationUpdateActivity del controlador de actividades de Teams.

EventType	Método de registro	Condición	Documentación de Teams
channelCreated	onTeamsChannelCreatedEvent	Se envía cada vez que se crea un nuevo canal en un equipo en el que se instala el bot.	Canal creado.
channelDeleted	onTeamsChannelDeletedEvent	Se envía cada vez que se elimina un canal en un equipo en el que está instalado el bot.	Canal eliminado.
channelRenamed	onTeamsChannelRenamedEvent	Se envía cada vez que se cambia el nombre de un canal en un equipo en el que está instalado el bot.	Se ha cambiado el nombre del canal.
channelRestored	onTeamsChannelRestoredEvent	Se envía cada vez que se restaura un canal que se eliminó anteriormente en un equipo en el que el bot ya está instalado.	Canal restaurado.
membersAdded	onTeamsMembersAddedEvent	Se envía la primera vez que el bot se agrega a una conversación y cada vez que se agrega un nuevo usuario a un chat de grupo o equipo en el que está instalado el bot.	Se han agregado miembros del equipo.
membersRemoved	onTeamsMembersRemovedEvent	Se envía si el bot se quita de un equipo y cada vez que se quita cualquier usuario de un equipo del que el bot es miembro.	Se han quitado miembros del equipo.
teamArchived	onTeamsTeamArchivedEvent	Se envía cuando se archiva el equipo en el que está instalado el bot.	Equipo archivado.
teamDeleted	onTeamsTeamDeletedEvent	Se envía cuando se ha eliminado el equipo en el que se encuentra el bot.	Equipo eliminado.
teamRenamed	onTeamsTeamRenamedEvent	Se envía cuando se ha cambiado el nombre del equipo en el que se encuentra el bot.	Se ha cambiado el nombre del equipo.
teamRestored	onTeamsTeamrestoredEvent	Se envía cuando se restaura un equipo eliminado previamente en el que se encuentra el bot.	Equipo restaurado.
teamUnarchived	onTeamsTeamUnarchivedEvent	Se envía cuando el equipo en el que está instalado el bot no está archivado.	Equipo no archivado.

Métodos para invalidar en una clase derivada

A continuación se muestra una lista de todos los controladores de actividad de Teams que se pueden invalidar para controlar las actividades de actualización de conversaciones de Teams.

EventType	Handler	Condición	Documentación de Teams
channelCreated	onTeamsChannelCreated	Se envía cada vez que se crea un nuevo canal en un equipo en el que se instala el bot.	Canal creado.
channelDeleted	onTeamsChannelDeleted	Se envía cada vez que se elimina un canal en un equipo en el que está instalado el bot.	Canal eliminado.
channelRenamed	onTeamsChannelRenamed	Se envía cada vez que se cambia el nombre de un canal en un equipo en el que está instalado el bot.	Se ha cambiado el nombre del canal.
channelRestored	onTeamsChannelRestored	Se envía cada vez que se restaura un canal que se eliminó anteriormente en un equipo en el que el bot ya está instalado.	Canal restaurado.
membersAdded	onTeamsMembersAdded	De forma predeterminada, llama al método ActivityHandler.onMembersAdded. Se envía la primera vez que el bot se agrega a una conversación y cada vez que se agrega un nuevo usuario a un chat de grupo o equipo en el que está instalado el bot.	Se han agregado miembros del equipo.
membersRemoved	onTeamsMembersRemoved	De forma predeterminada, llama al método ActivityHandler.onMembersRemoved. Se envía si el bot se quita de un equipo y cada vez que se quita cualquier usuario de un equipo del que el bot es miembro.	Se han quitado miembros del equipo.
teamArchived	onTeamsTeamArchived	Se envía cuando se archiva el equipo en el que está instalado el bot.	Equipo archivado.
teamDeleted	onTeamsTeamDeleted	Se envía cuando se ha eliminado el equipo en el que se encuentra el bot.	Equipo eliminado.
teamRenamed	onTeamsTeamRenamed	Se envía cuando se ha cambiado el nombre del equipo en el que se encuentra el bot.	Se ha cambiado el nombre del equipo.
teamRestored	onTeamsTeamRestored	Se envía cuando se restaura un equipo eliminado previamente en el que se encuentra el bot.	Equipo restaurado.
teamUnarchived	onTeamsTeamUnarchived	Se envía cuando el equipo en el que está instalado el bot no está archivado.	Equipo no archivado.

Java

A continuación se muestra una lista de todos los controladores de actividades de Teams a los que se llama desde el método onConversationUpdateActivity del controlador de actividades de Teams.

EventType	Handler	Condición	Documentación de Teams
channelCreated	onTeamsChannelCreated	Se envía cada vez que se crea un nuevo canal en un equipo en el que se instala el bot.	Canal creado.
channelDeleted	onTeamsChannelDeleted	Se envía cada vez que se elimina un canal en un equipo en el que está instalado el bot.	Canal eliminado.
channelRenamed	onTeamsChannelRenamed	Se envía cada vez que se cambia el nombre de un canal en un equipo en el que está instalado el bot.	Se ha cambiado el nombre del canal.
channelRestored	onTeamsChannelRestored	Se envía cada vez que se restaura un canal que se eliminó anteriormente en un equipo en el que el bot ya está instalado.	Canal restaurado.
membersAdded	onTeamsMembersAdded	De forma predeterminada, llama al método ActivityHandler.onMembersAdded. Se envía la primera vez que el bot se agrega a una conversación y cada vez que se agrega un nuevo usuario a un chat de grupo o equipo en el que está instalado el bot.	Se han agregado miembros del equipo.
membersRemoved	onTeamsMembersRemoved	De forma predeterminada, llama al método ActivityHandler.onMembersRemoved. Se envía si el bot se quita de un equipo y cada vez que se quita cualquier usuario de un equipo del que el bot es miembro.	Se han quitado miembros del equipo.
teamArchived	onTeamsTeamArchived	Se envía cuando se archiva el equipo en el que está instalado el bot.	Equipo archivado.
teamDeleted	onTeamsTeamDeleted	Se envía cuando se ha eliminado el equipo en el que se encuentra el bot.	Equipo eliminado.
teamRenamed	onTeamsTeamRenamed	Se envía cuando se ha cambiado el nombre del equipo en el que se encuentra el bot.	Se ha cambiado el nombre del equipo.
teamRestored	onTeamsTeamRestored	Se envía cuando se restaura un equipo eliminado previamente en el que se encuentra el bot.	Equipo restaurado.
teamUnarchived	onTeamsTeamUnarchived	Se envía cuando el equipo en el que está instalado el bot no está archivado.	Equipo no archivado.

Python

A continuación se muestra una lista de todos los controladores de actividades de Teams a los que se llama desde el método on_conversation_update_activity del controlador de actividades de Teams.

EventType	Handler	Condición	Documentación de Teams
channelCreated	on_teams_channel_created	Se envía cada vez que se crea un nuevo canal en un equipo en el que se instala el bot.	Canal creado.
channelDeleted	on_teams_channel_deleted	Se envía cada vez que se elimina un canal en un equipo en el que está instalado el bot.	Canal eliminado.
channelRenamed	on_teams_channel_renamed	Se envía cada vez que se cambia el nombre de un canal en un equipo en el que está instalado el bot.	Se ha cambiado el nombre del canal.
channelRestored	on_teams_channel_restored	Se envía cada vez que se restaura un canal que se eliminó anteriormente en un equipo en el que el bot ya está instalado.	Canal restaurado.
membersAdded	on_teams_members_added	De forma predeterminada, llama al método de clase base on_members_added_activity. Se envía la primera vez que el bot se agrega a una conversación y cada vez que se agrega un nuevo usuario a un chat de grupo o equipo en el que está instalado el bot.	Se han agregado miembros del equipo.
membersRemoved	on_teams_members_removed	De forma predeterminada, llama al método de clase base on_members_removed_activity. Se envía si el bot se quita de un equipo y cada vez que se quita cualquier usuario de un equipo del que el bot es miembro.	Se han quitado miembros del equipo.
teamArchived	on_teams_team_archived	Se envía cuando se archiva el equipo en el que está instalado el bot.	Equipo archivado.
teamDeleted	on_teams_team_deleted	Se envía cuando se ha eliminado el equipo en el que se encuentra el bot.	Equipo eliminado.
teamRenamed	on_teams_team_renamed	Se envía cuando se ha cambiado el nombre del equipo en el que se encuentra el bot.	Se ha cambiado el nombre del equipo.
teamRestored	on_teams_team_restored	Se envía cuando se restaura un equipo eliminado previamente en el que se encuentra el bot.	Equipo restaurado.
teamUnarchived	on_teams_team_unarchived	Se envía cuando el equipo en el que está instalado el bot no está archivado.	Equipo no archivado.

Actividades de eventos de Teams

En la tabla siguiente se enumeran las actividades de eventos específicas de Teams que Teams envía a un bot. Las actividades de eventos enumeradas son para los bots de conversación de Teams.

C#

Estos son los controladores de actividad de eventos específicos de Teams a los que se llama desde el OnEventActivityAsync controlador de actividad de Teams .

Tipos de eventos	Handler	Descripción
application/vnd.microsoft.meetingEnd	OnTeamsMeetingEndAsync	El bot está asociado a una reunión que acaba de finalizar.
application/vnd.microsoft.meetingStart	OnTeamsMeetingStartAsync	El bot está asociado a una reunión que acaba de comenzar.

JavaScript

Estos son los controladores de actividad de eventos específicos de Teams a los que se llama desde el onEventActivity controlador de actividad de Teams .

Tipos de eventos	Handler	Descripción
application/vnd.microsoft.meetingEnd	onTeamsMeetingEnd	El bot está asociado a una reunión que acaba de finalizar.
application/vnd.microsoft.meetingStart	onTeamsMeetingStart	El bot está asociado a una reunión que acaba de comenzar.

Java

Estos son los controladores de actividad de eventos específicos de Teams a los que se llama desde el onEventActivity controlador de actividad de Teams .

Tipos de eventos	Handler	Descripción
application/vnd.microsoft.meetingEnd	onTeamsMeetingEnd	El bot está asociado a una reunión que acaba de finalizar.
application/vnd.microsoft.meetingStart	onTeamsMeetingStart	El bot está asociado a una reunión que acaba de comenzar.

Python

Estos son los controladores de actividad de eventos específicos de Teams a los que se llama desde el on_event_activity controlador de actividad de Teams .

Tipos de eventos	Handler	Descripción
application/vnd.microsoft.meetingEnd	on_teams_meeting_end_event	El bot está asociado a una reunión que acaba de finalizar.
application/vnd.microsoft.meetingStart	on_teams_meeting_start_event	El bot está asociado a una reunión que acaba de comenzar.

Actividades de invocación de Teams

En la tabla siguiente se enumeran las actividades de invocación específicas de Teams que Teams envía a un bot. Las actividades de invocación enumeradas son para los bots de conversación de Teams. Bot Framework SDK también admite invocaciones específicas de las extensiones de mensajería. Para obtener más información, consulte el artículo de Teams ¿Qué son las extensiones de mensajería?

Nota:

La documentación de la plataforma de Microsoft Teams y la biblioteca cliente de JavaScript de Teams (TeamsJS) hacen referencia a módulos de tareas como diálogos modales. Para más información, consulte Diálogos.

C#

Esta es una lista de todos los controladores de actividad de Teams a los que se llama desde el OnInvokeActivityAsync controlador de actividad de Teams :

Tipos de invocación	Handler	Descripción
actionableMessage/executeAction	OnTeamsO365ConnectorCardActionAsync	Acción de tarjeta del conector de O365 de Teams.
CardAction.Invoke	OnTeamsCardActionInvokeAsync	Invocación de acción de tarjeta de Teams.
fileConsent/invoke	OnTeamsFileConsentAcceptAsync	Aceptación de consentimiento de archivo de Teams.
fileConsent/invoke	OnTeamsFileConsentAsync	Consentimiento de archivo de Teams.
fileConsent/invoke	OnTeamsFileConsentDeclineAsync	Consentimiento de archivo de Teams.
signin/verifyState	OnTeamsSigninVerifyStateAsync	Comprobación de estado de inicio de sesión de Teams.
task/fetch	OnTeamsTaskModuleFetchAsync	Captura del módulo de tareas de Teams.
task/submit	OnTeamsTaskModuleSubmitAsync	Envío del módulo de tareas de Teams.

JavaScript

Esta es una lista de todos los controladores de actividad de Teams a los que se llama desde el onInvokeActivity controlador de actividad de Teams :

Tipos de invocación	Handler	Descripción
actionableMessage/executeAction	handleTeamsO365ConnectorCardAction	Acción de tarjeta del conector de O365 de Teams.
CardAction.Invoke	handleTeamsCardActionInvoke	Invocación de acción de tarjeta de Teams.
fileConsent/invoke	handleTeamsFileConsentAccept	Aceptación de consentimiento de archivo de Teams.
fileConsent/invoke	handleTeamsFileConsent	Consentimiento de archivo de Teams.
fileConsent/invoke	handleTeamsFileConsentDecline	Consentimiento de archivo de Teams.
signin/verifyState	handleTeamsSigninVerifyState	Comprobación de estado de inicio de sesión de Teams.
task/fetch	handleTeamsTaskModuleFetch	Captura del módulo de tareas de Teams (cuadro de diálogo modal).
task/submit	handleTeamsTaskModuleSubmit	Envío del módulo de tareas de Teams (cuadro de diálogo modal).

Java

Esta es una lista de todos los controladores de actividad de Teams a los que se llama desde el onInvokeActivity controlador de actividad de Teams :

Tipos de invocación	Handler	Descripción
fileConsent/invoke	onTeamsFileConsent	Consentimiento de archivo de Teams.
actionableMessage/executeAction	onTeamsO365ConnectorCardAction	Acción de tarjeta del conector de O365 de Teams.
task/fetch	onTeamsTaskModuleFetch	Captura del módulo de tareas de Teams.
task/submit	onTeamsTaskModuleSubmit	Envío del módulo de tareas de Teams.
pestaña/capturar	onTeamsTabFetch	Captura de pestaña Teams.
pestaña/enviar	onTeamsTabSubmit	Envío de pestaña Teams.
CardAction.Invoke	onTeamsCardActionInvoke	Invocación de acción de tarjeta de Teams.
fileConsent/invoke	onTeamsFileConsentAccept	Aceptación de consentimiento de archivo de Teams.
fileConsent/invoke	onTeamsFileConsentDecline	Consentimiento de archivo de Teams.
signin/verifyState	onTeamsSigninVerifyState	Comprobación de estado de inicio de sesión de Teams.

Python

Esta es una lista de todos los controladores de actividad de Teams a los que se llama desde el on_invoke_activity controlador de actividad de Teams :

Tipos de invocación	Handler	Descripción
actionableMessage/executeAction	on_teams_o365_connector_card_action	Acción de tarjeta del conector de O365 de Teams.
CardAction.Invoke	on_teams_card_action_invoke	Invocación de acción de tarjeta de Teams.
fileConsent/invoke	on_teams_file_consent_accept	Aceptación de consentimiento de archivo de Teams.
fileConsent/invoke	on_teams_file_consent	Consentimiento de archivo de Teams.
fileConsent/invoke	on_teams_file_consent_decline	Rechazo del consentimiento del archivo de Teams.
signin/verifyState	on_teams_signin_verify_state	Comprobación de estado de inicio de sesión de Teams.
task/fetch	on_teams_task_module_fetch	Captura del módulo de tareas de Teams.
task/submit	on_teams_task_module_submit	Envío del módulo de tareas de Teams.

Pasos siguientes

Para crear bots para Teams, consulte la documentación para desarrolladores de Microsoft Teams.