Compilar extensões de mensagens.

As extensões de mensagens permitem que os utilizadores interajam com o seu serviço Web através 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 destas interações podem ser devolvidos ao cliente do Teams como um card formatado.

O artigo fornece uma descrição geral das extensões de mensagens, casos de utilização, funcionalidade, comandos de ação e pesquisa e desfraldamento de ligações.

A imagem seguinte apresenta as localizações a partir das quais as extensões de mensagens podem ser invocadas:

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

Entenda como funcionam as extensões de mensagem

Uma extensão de mensagem é composta por um serviço Web alojado por si e por um manifesto de aplicação que define a localização onde o seu serviço Web é invocado no cliente do Teams. O serviço Web utiliza o esquema de mensagens do Bot Framework e o protocolo de comunicação segura, pelo que tem de registar o serviço Web como um bot no Bot Framework.

No manifesto da aplicação (anteriormente denominado manifesto da aplicação Teams), é definida uma extensão de mensagem única com até 10 comandos diferentes. Cada comando define um tipo, como ação ou pesquisa e as localizações no cliente a partir do qual a extensão de mensagem é invocada. As localizações de invocação incluem a área de composição de mensagens, a barra de comandos e a mensagem. Ao invocar, o serviço Web recebe uma mensagem HTTPS com um payload JSON com todas as informações relevantes. Responda com um payload JSON para informar o cliente do Teams da próxima interação a ativar.

Tipos de comandos de extensão de mensagens

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 a autenticação e a configuração, estão disponíveis para ambos os tipos de comandos.

Comandos de ação

Os comandos de ação são utilizados para apresentar aos utilizadores um pop-up modal para recolher ou apresentar informações. Quando o utilizador submete o formulário, o seu serviço Web responde ao inserir uma mensagem na conversação diretamente ou na área de composição de mensagens. Mais tarde, o utilizador pode submeter a mensagem. Para fluxos de trabalho mais complexos, pode ligar vários formulários.

Os comandos de ação são acionados a partir da área de composição de mensagens, da caixa de comando ou de uma mensagem. Quando o comando é invocado a partir de uma mensagem, o payload JSON inicial enviado para o bot inclui toda a mensagem a partir da qual foi invocado. A imagem seguinte apresenta a caixa de diálogo do comando de ação da extensão de mensagem (referida como módulo de tarefa no TeamsJS v1.x):

Comandos de pesquisa

Os comandos de pesquisa permitem que os utilizadores procurem informações num sistema externo. Para utilizar comandos de pesquisa, introduza uma consulta manualmente na caixa de pesquisa ou insira uma ligação para um domínio monitorizado na área de composição de mensagens e, em seguida, incorpore os resultados da pesquisa numa mensagem. Num fluxo de comando de pesquisa simples, a mensagem de invocação inicial inclui a cadeia de pesquisa submetida pelo utilizador. 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 acionados a partir da área de composição da mensagem ou da caixa de comando, mas não de uma mensagem. Não podem ser acionados a partir de uma mensagem. A imagem seguinte apresenta a caixa de diálogo do comando de pesquisa da extensão de mensagem:

Desenrolamento de link

Quando um URL é colado na área de composição de mensagens, é invocado um serviço Web. Essa funcionalidade é conhecida como desenrolamento de link. Pode subscrever para receber uma mensagem de invocação quando os URLs que contêm um domínio específico são colados na área de composição de mensagens. O seu serviço Web pode desvendar o URL numa card detalhada, fornecendo mais informações do que a pré-visualização padrão do site card. Pode adicionar botões para permitir que os utilizadores tomem medidas imediatamente sem sair do cliente do Teams. As imagens seguintes apresentam a funcionalidade de desfraldamento da ligação quando uma ligação é colada numa extensão de mensagem:

Compilar extensões de mensagens.

Para criar uma extensão de mensagem, se ainda não tiver uma, existem duas formas:

• Criar extensões de mensagens com a API (baseada em API): pode criar facilmente uma extensão de mensagem a partir de uma API existente. Para este método, é necessário um documento de Descrição de OpenAPI (OAD).

• Criar extensões de mensagens com o Bot Framework (baseado em bots): se quiser uma experiência de conversação individual, pode criar uma nova extensão de mensagem a partir de um bot.

A tabela seguinte ajuda-o a selecionar um tipo de extensão de mensagem para começar:

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

Exemplo de código