Compilar extensões de mensagens.

As extensões de mensagem permitem que os usuários se envolvam com seu serviço Web por meio de botões e formulários no cliente do Microsoft Teams. Os usuários podem pesquisar ou iniciar ações em um sistema externo a partir da área de redação da mensagem, da caixa de comando ou diretamente de uma mensagem. Os resultados dessas interações podem ser retornados ao cliente do Teams como um cartão altamente formatado.

Importante

As extensões de mensagem estão disponíveis em ambientes do GCC (Government Community Cloud), GCC-High e DoD (Departamento de Defesa ).

Este documento fornece uma visão geral de extensões de mensagem, tarefas executadas em vários cenários, o funcionamento de extensões de mensagem, comandos de ação e pesquisa e desenrolamento de link.

A imagem a seguir exibe os locais de onde as extensões de mensagem podem ser invocadas:

Observação

@mentioning não há suporte para extensões de mensagem na caixa de composição.

Desktop

Dispositivo móvel

Cenários em que as extensões de mensagem são usadas

Cenário	Exemplo
Você precisa de um sistema externo para executar uma ação e retornar o resultado para sua conversa.	Reserve um recurso e permita que o canal saiba o intervalo de tempo reservado.
Você precisa pesquisar algo em um sistema externo e compartilhar os resultados com a conversa.	Pesquise um item de trabalho no Azure DevOps e compartilhe-o com o grupo como um Cartão Adaptável.
Você deseja concluir uma tarefa complexa envolvendo várias etapas ou uma grande quantidade de informações em um sistema externo e compartilhar os resultados com uma conversa.	Crie um bug no seu sistema de acompanhamento com base em uma mensagem do Teams, atribua esse bug a um usuário e envie um cartão para o thread da conversa com os detalhes do bug.

Entenda como funcionam as extensões de mensagem

Uma extensão de mensagem consiste em um serviço Web que você hospeda e um manifesto de aplicativo, que especifica o local no cliente do Teams em que seu serviço Web é invocado. O serviço Web utiliza o esquema de mensagens do Bot Framework e o protocolo de comunicação segura, portanto, você deve registrar seu serviço Web como um bot no Bot Framework.

Observação

Embora seja possível criar manualmente o serviço Web, recomendamos usar o SDK do Bot Framework para trabalhar com o protocolo.

No manifesto do aplicativo (anteriormente chamado como manifesto do aplicativo teams), uma única extensão de mensagem é definida com até 10 comandos diferentes. Cada comando define um tipo, como ação ou pesquisa e os locais no cliente de onde ele é invocado. Os locais de invocação incluem a área de mensagem de composição, a barra de comandos e a mensagem. Ao invocar, o serviço Web recebe uma mensagem HTTPS com uma carga JSON com todas as informações relevantes. Responda com uma carga JSON para informar o cliente do Teams sobre a próxima interação a ser habilitada.

Tipos de comandos de extensão de mensagem

Há dois tipos de comandos de extensão de mensagem: comando de ação e comando de pesquisa. O tipo de comando de extensão de mensagem define os elementos de interface do usuário e os fluxos de interação disponíveis para seu serviço Web. Determinadas interações, como autenticação e configuração, estão disponíveis para ambos os tipos de comandos.

Comandos de ação

Os comandos de ação são usados para apresentar aos usuários um pop-up modal para coletar ou exibir informações. Quando o usuário envia o formulário, seu serviço Web responde inserindo uma mensagem na conversa diretamente ou na área de mensagem de composição. Posteriormente, o usuário pode enviar a mensagem. Para fluxos de trabalho mais complexos, você pode vincular vários formulários juntos.

Os comandos de ação são disparados da área de mensagem de composição, da caixa de comando ou de uma mensagem. Quando o comando é invocado de uma mensagem, a carga JSON inicial enviada ao bot inclui toda a mensagem da qual foi invocada. A imagem a seguir exibe a caixa de diálogo comando de ação de extensão de mensagem (conhecido como módulo de tarefa no TeamsJS v1.x):

Comandos de pesquisa

Os comandos de pesquisa permitem que os usuários pesquisem informações em um sistema externo manualmente por meio de uma caixa de pesquisa ou colando um link a um domínio monitorado na área de mensagem de composição e insira os resultados da pesquisa em uma mensagem. Em um fluxo de comando de pesquisa simples, a mensagem de invocação inicial inclui a cadeia de caracteres de pesquisa enviada pelo usuário. Você responderá com uma lista de cartões e visualizações de cartões. O cliente do Teams renderiza uma lista de visualizações de cartão para o usuário. Quando o usuário seleciona um cartão, o cartão de tamanho completo é inserido na área de redação da mensagem.

Os cartões são disparados da área de mensagem de composição ou da caixa de comando, mas não de uma mensagem. Eles não podem ser disparados de uma mensagem. A imagem a seguir exibe a caixa de diálogo comando de pesquisa de extensão de mensagem:

Observação

Para obter mais informações sobre cartões, consulte o que são cartões.

Desenrolamento de link

Observação

A desenrolamento de link só tem suporte para extensões de mensagem baseadas em bot.

Quando uma URL é colada na área de mensagem de composição, um serviço Web é invocado. Essa funcionalidade é conhecida como desenrolamento de link. Você pode assinar para receber uma invocação quando URLs que contêm um domínio específico são coladas na área de mensagem de composição. Seu serviço Web pode desenrolar a URL em um cartão detalhado, fornecendo mais informações do que a versão prévia do site padrão cartão. Você pode adicionar botões para permitir que os usuários tomem medidas imediatamente sem deixar o cliente do Teams. As imagens a seguir exibem o recurso de desenrolamento de link quando um link é colado em uma extensão de mensagem:

Compilar extensões de mensagens.

Para criar uma extensão de mensagem, se você ainda não tiver uma, há duas maneiras:

• Criar extensões de mensagem usando a API (baseada em API): você pode criar facilmente uma extensão de mensagem de uma API existente. Um documento OAD (OpenAPI Description) é necessário para esse método.

• Criar extensões de mensagem usando o Bot Framework (baseado em bot): se você quiser uma experiência de conversa individual, poderá criar uma nova extensão de mensagem de um bot.

A tabela a seguir ajuda você a selecionar um tipo de extensão de mensagem para começar:

Extensão de mensagem baseada em API

• Mais simples e rápido para criar e manter.
• A extensão de mensagem usa uma API.
• Nenhum código ou recursos adicionais para a lógica do bot são necessários.
• Ideal para cenários em que a extensão de mensagem só precisa se comunicar com um serviço Web e não precisa de nenhuma lógica complexa ou gerenciamento de estado.
• O tráfego é privatizado, pois eles não dependem da infraestrutura de bots do Azure.
• Dá suporte a comandos de pesquisa.

Extensão de mensagem baseada em bot

• Mais flexível.
• A extensão de mensagem usa uma Estrutura do Bot.
• Pode aproveitar as funcionalidades completas de um bot.
• Ideal para cenários em que a extensão de mensagem precisa se comunicar com vários serviços, gerenciar interações lógicas ou de usuário complexas ou manter o estado entre sessões.
• Dá suporte a comandos de ação, comandos de pesquisa e desenrolamento de link.

Selecione uma opção para começar a criar uma extensão de mensagem:

Exemplo de código

Nome de exemplo	Descrição	.NET	Node.js	Python	Manifesto
Extensão de mensagem com comandos baseados em ação	Este exemplo mostra como definir comandos de ação, criar caixa de diálogo e responder à ação de envio de diálogo.	View	View	View	View
Extensão de mensagem com comandos baseados em pesquisa	Este exemplo mostra como criar uma extensão de mensagem baseada em pesquisa. Ele pesquisa pacotes nuget e exibe os resultados na extensão de mensagens baseada em pesquisa.	View	View	View	Exibir
Visualização da ação de extensão de mensagem	Este exemplo mostra como usar a visualização de ação em Extensões de Mensagens usando o Bot Framework v4.	View	View	NA	Exibir
Ação de extensão de mensagem para agendamento de tarefas	Este exemplo mostra como agendar uma tarefa do comando de ação de extensão de mensagem e obter um lembrete cartão em uma data e hora agendadas.	View	View	NA	Exibir