Como os bots do Microsoft Teams funcionam

APLICA-SE A: SDK v4

Este artigo se baseia no que você aprendeu em Como os bots funcionam e Conversas orientadas por eventos. Familiarize-se com esses artigos antes de continuar.

A principal diferença nos bots desenvolvidos para o Microsoft Teams é a forma como as atividades são tratadas. O Manipulador de atividades do Teams deriva do manipulador de atividades e processa tipos de atividades específicos do Teams antes de processar tipos de atividades mais gerais.

Observação

Os SDKs JavaScript, C# e Python do Bot Framework continuarão a ser compatíveis. No entanto, o SDK Java está sendo desativado, com o suporte final de longo prazo terminando em novembro de 2023.

Os bots existentes criados com o SDK para Java continuarão a funcionar.

Para a criação de novos bots, considere usar o Power Virtual Agents e ler sobre como escolher a solução de chatbot correta.

Para obter mais informações, confira O futuro da criação de bots.

Manipulador de atividade do Teams

Para criar um bot para o Teams, derive seu bot da classe do manipulador de atividades do Teams. Quando esse bot recebe uma atividade, ele roteia a atividade por meio de vários manipuladores de atividades. O manipulador inicial de base é o manipulador de turnos, que roteia a atividade para um manipulador com base no tipo da atividade. O manipulador de turnos chama o manipulador projetado para manipular o tipo específico de atividade recebido. A classe do manipulador de atividade do Teams é derivada da classe do manipulador de atividades. Além dos tipos de atividade que o manipulador de atividades pode processar, a classe do manipulador de atividades do Teams inclui manipuladores adicionais para atividades específicas do Teams.

Um bot que deriva do manipulador de atividades do Teams é semelhante a um bot que deriva diretamente da classe do manipulador de atividades. No entanto, o Teams inclui informações adicionais nas atividades conversationUpdate e envia invoke específico do Teams e atividades event.

C#

Quando o manipulador de atividades do seu bot no Teams recebe uma atividade de mensagem, o manipulador de turnos direciona a atividade de mensagem de entrada para seu manipulador OnMessageActivityAsync, de maneira semelhante a um bot baseado em manipulador de atividades. No entanto, quando o bot do Teams recebe uma atividade de atualização de conversa, a versão do manipulador OnConversationUpdateActivityAsync do Teams processa a atividade.

Não há implementação base para a maioria desses manipuladores de atividade específicos do Teams. Será preciso substituir esses manipuladores e fornecer a lógica apropriada para seu bot.

JavaScript

Quando o manipulador de atividades do seu bot no Teams recebe uma atividade de mensagem, o manipulador de turnos direciona a atividade de mensagem de entrada para seu manipulador onMessage, de maneira semelhante a um bot baseado em manipulador de atividades. No entanto, quando o bot do Teams recebe uma atividade de atualização de conversa, a versão do manipulador dispatchConversationUpdateActivity do Teams processa a atividade.

Não há implementação base para a maioria desses manipuladores de atividade específicos do Teams. Será preciso substituir esses manipuladores e fornecer a lógica apropriada para seu bot.

Ao substituir esses manipuladores de atividades específicos do Teams, defina a lógica do bot e, em seguida, chame next() no final. Ao chamar next(), você faz com que o próximo manipulador seja executado.

Java

Quando o manipulador de atividades do seu bot no Teams recebe uma atividade de mensagem, o manipulador de turnos direciona a atividade de mensagem de entrada para seu manipulador onMessageActivity, de maneira semelhante a um bot baseado em manipulador de atividades. No entanto, quando o bot do Teams recebe uma atividade de atualização de conversa, a versão do manipulador onConversationUpdateActivity do Teams processa a atividade.

Não há implementação base para a maioria desses manipuladores de atividade específicos do Teams. Será preciso substituir esses manipuladores e fornecer a lógica apropriada para seu bot.

Python

Quando o manipulador de atividades do seu bot no Teams recebe uma atividade de mensagem, o manipulador de turnos direciona a atividade de mensagem de entrada para seu manipulador on_message_activity, de maneira semelhante a um bot baseado em manipulador de atividades. No entanto, quando o bot do Teams recebe uma atividade de atualização de conversa, a versão do manipulador on_conversation_update_activity do Teams processa a atividade.

Não há implementação base para a maioria desses manipuladores de atividade específicos do Teams. Será preciso substituir esses manipuladores e fornecer a lógica apropriada para seu bot.

Todos os manipuladores de atividades descritos na seção de manipulação de atividades do artigo Conversas orientadas por eventos usando um manipulador de atividades continuarão funcionando como fazem com um bot que não seja do Teams, exceto para lidar com as atividades adicionadas e removidas de membros, essas atividades serão diferentes no contexto de uma equipe, em que o novo membro é adicionado à equipe, em oposição a um encadeamento de mensagens. Para obter mais informações, confira Atividades de atualização de conversa do Teams.

Para implementar sua lógica para esses manipuladores de atividade específicos do Teams, substitua os métodos do seu bot.

Lógica de bot do Teams

A lógica do bot processa as atividades de entrada de um ou mais canais e gera atividades de saída em resposta. Isso ainda é verdadeiro para o bot derivado da classe do manipulador de atividade do Teams, que primeiro verifica se há atividades do Teams e, em seguida, passa todas as outras atividades para o manipulador de atividade do Bot Framework.

Atividades de atualização de instalação do Teams

Adicione um manipulador para o evento de atualização de instalação para permitir que seu bot:

• Envie uma mensagem introdutória quando estiver instalado em um thread de conversa.
• Limpe os dados do usuário e do thread quando for desinstalado de um thread.

Confira Evento de atualização de instalação nos documentos do Teams para obter mais informações.

Atividades de atualização de conversa de equipes

A tabela a seguir lista os eventos do Teams que geram uma atividade de atualização de conversa em um bot. O artigo do Microsoft Teams Eventos de atualização de conversa descreve como usar cada um desses eventos.

C#

Veja a seguir uma lista de todos os manipuladores de atividades do Teams chamados do método OnConversationUpdateActivityAsync do manipulador de atividades do Teams.

EventType	Manipulador	Condição	Documentação do Teams
channelCreated	OnTeamsChannelCreatedAsync	Enviado sempre que um novo canal é criado em uma equipe na qual seu bot está instalado.	Canal criado.
channelDeleted	OnTeamsChannelDeletedAsync	Enviado sempre que um canal é excluído em uma equipe na qual seu bot está instalado.	Canal excluído.
channelRenamed	OnTeamsChannelRenamedAsync	Enviado sempre que um canal é renomeado em uma equipe na qual seu bot está instalado.	Canal renomeado.
channelRestored	OnTeamsChannelRestoredAsync	Enviado sempre que um canal que foi excluído anteriormente é restaurado em uma equipe na qual seu bot já está instalado.	Canal restaurado.
membersAdded	OnTeamsMembersAddedAsync	Por padrão, chama o método ActivityHandler.OnMembersAddedAsync. Enviado na primeira vez que o bot é adicionado a uma conversa e toda vez que um novo usuário é adicionado a uma equipe ou chat em grupo no qual seu bot está instalado.	Membros da equipe adicionados.
membersRemoved	OnTeamsMembersRemovedAsync	Por padrão, chama o método ActivityHandler.OnMembersRemovedAsync. Enviado se o bot for removido de uma equipe e toda vez que algum usuário for removido de uma equipe da qual o bot seja membro.	Membros da equipe removidos.
teamArchived	OnTeamsTeamArchivedAsync	Enviado quando a equipe na qual o bot está instalado é arquivada.	Equipe arquivada.
teamDeleted	OnTeamsTeamDeletedAsync	Enviado quando a equipe em que seu bot está foi excluída.	Equipe excluída.
teamRenamed	OnTeamsTeamRenamedAsync	Enviado quando a equipe em que seu bot está foi renomeada.	Equipe renomeada.
teamRestored	OnTeamsTeamRestoredAsync	Enviado quando uma equipe anteriormente excluída, na qual seu bot está, é restaurada.	Equipe restaurada.
teamUnarchived	OnTeamsTeamUnarchivedAsync	Enviado quando a equipe na qual o bot está instalado é desarquivada.	Equipe desarquivada.

JavaScript

Os desenvolvedores podem manipular atividades de atualização de conversa enviadas do Microsoft Teams por meio de dois métodos:

1. Para passar um retorno de chamada, use métodos que começam com one terminam com Event (por exemplo, o método onTeamsMembersAddedEvent).
2. Ao criar uma classe derivada, substitua os métodos que começam com on e não terminam com Event (por exemplo, o método onTeamsMembersAdded).

Os desenvolvedores devem usar apenas uma destas opções: 1 ou 2, e não ambas para a mesma atividade. Ou seja, os desenvolvedores devem passar um retorno de chamada para o método onTeamsMembersAddedEventou substituir o método onTeamsMembersAdded em uma classe derivada, e não fazer as duas coisas.

Métodos para registrar um retorno de chamada

Veja a seguir uma lista de todos os emissores de atividades do Teams chamados do método dispatchConversationUpdateActivity do manipulador de atividades do Teams.

EventType	Método de registro	Condição	Documentação do Teams
channelCreated	onTeamsChannelCreatedEvent	Enviado sempre que um novo canal é criado em uma equipe na qual seu bot está instalado.	Canal criado.
channelDeleted	onTeamsChannelDeletedEvent	Enviado sempre que um canal é excluído em uma equipe na qual seu bot está instalado.	Canal excluído.
channelRenamed	onTeamsChannelRenamedEvent	Enviado sempre que um canal é renomeado em uma equipe na qual seu bot está instalado.	Canal renomeado.
channelRestored	onTeamsChannelRestoredEvent	Enviado sempre que um canal que foi excluído anteriormente é restaurado em uma equipe na qual seu bot já está instalado.	Canal restaurado.
membersAdded	onTeamsMembersAddedEvent	Enviado na primeira vez que o bot é adicionado a uma conversa e toda vez que um novo usuário é adicionado a uma equipe ou chat em grupo no qual seu bot está instalado.	Membros da equipe adicionados.
membersRemoved	onTeamsMembersRemovedEvent	Enviado se o bot for removido de uma equipe e toda vez que algum usuário for removido de uma equipe da qual o bot seja membro.	Membros da equipe removidos.
teamArchived	onTeamsTeamArchivedEvent	Enviado quando a equipe na qual o bot está instalado é arquivada.	Equipe arquivada.
teamDeleted	onTeamsTeamDeletedEvent	Enviado quando a equipe em que seu bot está foi excluída.	Equipe excluída.
teamRenamed	onTeamsTeamRenamedEvent	Enviado quando a equipe em que seu bot está foi renomeada.	Equipe renomeada.
teamRestored	onTeamsTeamrestoredEvent	Enviado quando uma equipe anteriormente excluída, na qual seu bot está, é restaurada.	Equipe restaurada.
teamUnarchived	onTeamsTeamUnarchivedEvent	Enviado quando a equipe na qual o bot está instalado é desarquivada.	Equipe desarquivada.

Métodos para substituir em uma classe derivada

Veja a seguir uma lista de todos os manipuladores de atividades do Teams que podem ser substituídos para manipular atividades de atualização de conversa do Teams.

EventType	Manipulador	Condição	Documentação do Teams
channelCreated	onTeamsChannelCreated	Enviado sempre que um novo canal é criado em uma equipe na qual seu bot está instalado.	Canal criado.
channelDeleted	onTeamsChannelDeleted	Enviado sempre que um canal é excluído em uma equipe na qual seu bot está instalado.	Canal excluído.
channelRenamed	onTeamsChannelRenamed	Enviado sempre que um canal é renomeado em uma equipe na qual seu bot está instalado.	Canal renomeado.
channelRestored	onTeamsChannelRestored	Enviado sempre que um canal que foi excluído anteriormente é restaurado em uma equipe na qual seu bot já está instalado.	Canal restaurado.
membersAdded	onTeamsMembersAdded	Por padrão, chama o método ActivityHandler.onMembersAdded. Enviado na primeira vez que o bot é adicionado a uma conversa e toda vez que um novo usuário é adicionado a uma equipe ou chat em grupo no qual seu bot está instalado.	Membros da equipe adicionados.
membersRemoved	onTeamsMembersRemoved	Por padrão, chama o método ActivityHandler.onMembersRemoved. Enviado se o bot for removido de uma equipe e toda vez que algum usuário for removido de uma equipe da qual o bot seja membro.	Membros da equipe removidos.
teamArchived	onTeamsTeamArchived	Enviado quando a equipe na qual o bot está instalado é arquivada.	Equipe arquivada.
teamDeleted	onTeamsTeamDeleted	Enviado quando a equipe em que seu bot está foi excluída.	Equipe excluída.
teamRenamed	onTeamsTeamRenamed	Enviado quando a equipe em que seu bot está foi renomeada.	Equipe renomeada.
teamRestored	onTeamsTeamRestored	Enviado quando uma equipe anteriormente excluída, na qual seu bot está, é restaurada.	Equipe restaurada.
teamUnarchived	onTeamsTeamUnarchived	Enviado quando a equipe na qual o bot está instalado é desarquivada.	Equipe desarquivada.

Java

Veja a seguir uma lista de todos os manipuladores de atividades do Teams chamados do método onConversationUpdateActivity do manipulador de atividades do Teams.

EventType	Manipulador	Condição	Documentação do Teams
channelCreated	onTeamsChannelCreated	Enviado sempre que um novo canal é criado em uma equipe na qual seu bot está instalado.	Canal criado.
channelDeleted	onTeamsChannelDeleted	Enviado sempre que um canal é excluído em uma equipe na qual seu bot está instalado.	Canal excluído.
channelRenamed	onTeamsChannelRenamed	Enviado sempre que um canal é renomeado em uma equipe na qual seu bot está instalado.	Canal renomeado.
channelRestored	onTeamsChannelRestored	Enviado sempre que um canal que foi excluído anteriormente é restaurado em uma equipe na qual seu bot já está instalado.	Canal restaurado.
membersAdded	onTeamsMembersAdded	Por padrão, chama o método ActivityHandler.onMembersAdded. Enviado na primeira vez que o bot é adicionado a uma conversa e toda vez que um novo usuário é adicionado a uma equipe ou chat em grupo no qual seu bot está instalado.	Membros da equipe adicionados.
membersRemoved	onTeamsMembersRemoved	Por padrão, chama o método ActivityHandler.onMembersRemoved. Enviado se o bot for removido de uma equipe e toda vez que algum usuário for removido de uma equipe da qual o bot seja membro.	Membros da equipe removidos.
teamArchived	onTeamsTeamArchived	Enviado quando a equipe na qual o bot está instalado é arquivada.	Equipe arquivada.
teamDeleted	onTeamsTeamDeleted	Enviado quando a equipe em que seu bot está foi excluída.	Equipe excluída.
teamRenamed	onTeamsTeamRenamed	Enviado quando a equipe em que seu bot está foi renomeada.	Equipe renomeada.
teamRestored	onTeamsTeamRestored	Enviado quando uma equipe anteriormente excluída, na qual seu bot está, é restaurada.	Equipe restaurada.
teamUnarchived	onTeamsTeamUnarchived	Enviado quando a equipe na qual o bot está instalado é desarquivada.	Equipe desarquivada.

Python

Veja a seguir uma lista de todos os manipuladores de atividades do Teams chamados do método on_conversation_update_activity do manipulador de atividades do Teams.

EventType	Manipulador	Condição	Documentação do Teams
channelCreated	on_teams_channel_created	Enviado sempre que um novo canal é criado em uma equipe na qual seu bot está instalado.	Canal criado.
channelDeleted	on_teams_channel_deleted	Enviado sempre que um canal é excluído em uma equipe na qual seu bot está instalado.	Canal excluído.
channelRenamed	on_teams_channel_renamed	Enviado sempre que um canal é renomeado em uma equipe na qual seu bot está instalado.	Canal renomeado.
channelRestored	on_teams_channel_restored	Enviado sempre que um canal que foi excluído anteriormente é restaurado em uma equipe na qual seu bot já está instalado.	Canal restaurado.
membersAdded	on_teams_members_added	Por padrão, chama o método on_members_added_activity de classe base. Enviado na primeira vez que o bot é adicionado a uma conversa e toda vez que um novo usuário é adicionado a uma equipe ou chat em grupo no qual seu bot está instalado.	Membros da equipe adicionados.
membersRemoved	on_teams_members_removed	Por padrão, chama o método on_members_removed_activity de classe base. Enviado se o bot for removido de uma equipe e toda vez que algum usuário for removido de uma equipe da qual o bot seja membro.	Membros da equipe removidos.
teamArchived	on_teams_team_archived	Enviado quando a equipe na qual o bot está instalado é arquivada.	Equipe arquivada.
teamDeleted	on_teams_team_deleted	Enviado quando a equipe em que seu bot está foi excluída.	Equipe excluída.
teamRenamed	on_teams_team_renamed	Enviado quando a equipe em que seu bot está foi renomeada.	Equipe renomeada.
teamRestored	on_teams_team_restored	Enviado quando uma equipe anteriormente excluída, na qual seu bot está, é restaurada.	Equipe restaurada.
teamUnarchived	on_teams_team_unarchived	Enviado quando a equipe na qual o bot está instalado é desarquivada.	Equipe desarquivada.

Atividades do evento do Teams

A tabela a seguir lista as atividades de evento específicas do Teams que ele envia a um bot. As atividades de evento listadas são para bots de conversa no Teams.

C#

Esses são os manipuladores de atividades de eventos específicos do Teams chamados do manipulador OnEventActivityAsync de atividades do Teams.

Tipos de evento	Manipulador	Descrição
application/vnd.microsoft.meetingEnd	OnTeamsMeetingEndAsync	O bot está associado a uma reunião que acabou de terminar.
application/vnd.microsoft.meetingStart	OnTeamsMeetingStartAsync	O bot está associado a uma reunião que acabou de começar.

JavaScript

Esses são os manipuladores de atividades de eventos específicos do Teams chamados do manipulador onEventActivity de atividades do Teams.

Tipos de evento	Manipulador	Descrição
application/vnd.microsoft.meetingEnd	onTeamsMeetingEnd	O bot está associado a uma reunião que acabou de terminar.
application/vnd.microsoft.meetingStart	onTeamsMeetingStart	O bot está associado a uma reunião que acabou de começar.

Java

Esses são os manipuladores de atividades de eventos específicos do Teams chamados do manipulador onEventActivity de atividades do Teams.

Tipos de evento	Manipulador	Descrição
application/vnd.microsoft.meetingEnd	onTeamsMeetingEnd	O bot está associado a uma reunião que acabou de terminar.
application/vnd.microsoft.meetingStart	onTeamsMeetingStart	O bot está associado a uma reunião que acabou de começar.

Python

Esses são os manipuladores de atividades de eventos específicos do Teams chamados do manipulador on_event_activity de atividades do Teams.

Tipos de evento	Manipulador	Descrição
application/vnd.microsoft.meetingEnd	on_teams_meeting_end_event	O bot está associado a uma reunião que acabou de terminar.
application/vnd.microsoft.meetingStart	on_teams_meeting_start_event	O bot está associado a uma reunião que acabou de começar.

Atividades de invocação do Teams

A tabela a seguir lista as atividades de invocação específicas do Teams que ele envia a um bot. As atividades de invocação listadas se destinam a bots de conversas no Teams. O SDK do Bot Framework também dá suporte a invocações específicas para extensões de mensagens. Para obter mais informações, confira o artigo do Teams O que são extensões de mensagens.

Observação

A documentação da plataforma Microsoft Teams e a biblioteca de cliente JavaScript do Teams (TeamsJS) referem-se aos módulos de tarefas como caixas de diálogo modais. Para obter mais informações, veja Caixas de diálogo.

C#

Veja uma lista de todos os manipuladores de atividade do Teams chamados do manipulador OnInvokeActivityAsync de atividade do Teams:

Invocar tipos	Manipulador	Descrição
actionableMessage/executeAction	OnTeamsO365ConnectorCardActionAsync	Ação de Cartão do Conector O365 do Teams.
CardAction.Invoke	OnTeamsCardActionInvokeAsync	Invocação de Ação de Cartão do Teams.
fileConsent/invoke	OnTeamsFileConsentAcceptAsync	Aceitação de Consentimento do Arquivo do Teams.
fileConsent/invoke	OnTeamsFileConsentAsync	Consentimento do Arquivo do Teams.
fileConsent/invoke	OnTeamsFileConsentDeclineAsync	Consentimento do Arquivo do Teams.
signin/verifyState	OnTeamsSigninVerifyStateAsync	Estado de Verificação de Entrada do Teams.
task/fetch	OnTeamsTaskModuleFetchAsync	Busca de Módulo de Tarefa do Teams.
task/submit	OnTeamsTaskModuleSubmitAsync	Envio de Módulo de Tarefa do Teams.

JavaScript

Veja uma lista de todos os manipuladores de atividade do Teams chamados do manipulador onInvokeActivity de atividade do Teams:

Invocar tipos	Manipulador	Descrição
actionableMessage/executeAction	handleTeamsO365ConnectorCardAction	Ação de Cartão do Conector O365 do Teams.
CardAction.Invoke	handleTeamsCardActionInvoke	Invocação de Ação de Cartão do Teams.
fileConsent/invoke	handleTeamsFileConsentAccept	Aceitação de Consentimento do Arquivo do Teams.
fileConsent/invoke	handleTeamsFileConsent	Consentimento do Arquivo do Teams.
fileConsent/invoke	handleTeamsFileConsentDecline	Consentimento do Arquivo do Teams.
signin/verifyState	handleTeamsSigninVerifyState	Estado de Verificação de Entrada do Teams.
task/fetch	handleTeamsTaskModuleFetch	Módulo de tarefas do Teams (caixa de diálogo modal) Buscar.
task/submit	handleTeamsTaskModuleSubmit	Módulo de tarefas do Teams (caixa de diálogo modal) Enviar.

Java

Veja uma lista de todos os manipuladores de atividade do Teams chamados do manipulador onInvokeActivity de atividade do Teams:

Invocar tipos	Manipulador	Descrição
fileConsent/invoke	onTeamsFileConsent	Consentimento do Arquivo do Teams.
actionableMessage/executeAction	onTeamsO365ConnectorCardAction	Ação de Cartão do Conector O365 do Teams.
task/fetch	onTeamsTaskModuleFetch	Busca de Módulo de Tarefa do Teams.
task/submit	onTeamsTaskModuleSubmit	Envio de Módulo de Tarefa do Teams.
tab/fetch	onTeamsTabFetch	Busca da guia Teams.
tab/submit	onTeamsTabSubmit	Envio da guia Teams.
CardAction.Invoke	onTeamsCardActionInvoke	Invocação de Ação de Cartão do Teams.
fileConsent/invoke	onTeamsFileConsentAccept	Aceitação de Consentimento do Arquivo do Teams.
fileConsent/invoke	onTeamsFileConsentDecline	Consentimento do Arquivo do Teams.
signin/verifyState	onTeamsSigninVerifyState	Estado de Verificação de Entrada do Teams.

Python

Veja uma lista de todos os manipuladores de atividade do Teams chamados do manipulador on_invoke_activity de atividade do Teams:

Invocar tipos	Manipulador	Descrição
actionableMessage/executeAction	on_teams_o365_connector_card_action	Ação de Cartão do Conector O365 do Teams.
CardAction.Invoke	on_teams_card_action_invoke	Invocação de Ação de Cartão do Teams.
fileConsent/invoke	on_teams_file_consent_accept	Aceitação de Consentimento do Arquivo do Teams.
fileConsent/invoke	on_teams_file_consent	Consentimento do Arquivo do Teams.
fileConsent/invoke	on_teams_file_consent_decline	Recusa de Consentimento do Arquivo do Teams.
signin/verifyState	on_teams_signin_verify_state	Estado de Verificação de Entrada do Teams.
task/fetch	on_teams_task_module_fetch	Busca de Módulo de Tarefa do Teams.
task/submit	on_teams_task_module_submit	Envio de Módulo de Tarefa do Teams.

Próximas etapas

Para criar bots do Teams, consulte a documentação do Desenvolvedor do Microsoft Teams.