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 cartão formatado.

Importante

As extensões de mensagens estão disponíveis em ambientes de Cloud da Comunidade Governamental (GCC), GCC-High e Departamento de Defesa (DOD).

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:

Observação

• @mentioning as extensões de mensagens na caixa de composição não são suportadas.
• As opções de extensão de mensagens não são suportadas para conversas de grupo com utilizadores externos.

Desktop

Dispositivo móvel

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

Cenário	Exemplo
Precisa de um sistema externo para efetuar uma ação e devolver o resultado à sua conversação.	Reserve um recurso e permita que o canal saiba o intervalo de tempo reservado.
Tem de procurar algo num sistema externo e partilhar os resultados com a conversação.	Procure um item de trabalho no Azure DevOps e partilhe-o com o grupo como um Cartão Ajustável.
Quer concluir uma tarefa complexa que envolva vários passos ou grandes quantidades de informações num sistema externo e partilhar os resultados com uma conversação.	Crie um erro no seu sistema de controlo com base numa mensagem do Teams, atribua esse erro e envie um cartão para o tópico de conversação com os detalhes do erro.

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.

Observação

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

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:

Observação

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

Desenrolamento de link

Observação

A desfraldamento de ligações é suportada apenas para extensões de mensagens baseadas em bots.

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 desajustar o URL num cartão detalhado, fornecendo mais informações do que o cartão de pré-visualização do site padrão. 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:

Extensão de mensagem baseada em API

• Mais simples e rápido de criar e manter.
• A extensão de mensagem utiliza uma API.
• Não é necessário nenhum código ou recurso adicional para a lógica do bot.
• Ideal para cenários em que a extensão de mensagem só precisa de comunicar com um serviço Web e não precisa de qualquer lógica complexa ou gestão de estado.
• O tráfego é privatizado, uma vez que não dependem da infraestrutura de bots do Azure.
• Suporta comandos de pesquisa.

Extensão de mensagem baseada em bot

• Mais flexível.
• A extensão de mensagem utiliza um Bot Framework.
• Pode utilizar todas as capacidades de um bot.
• Ideal para cenários em que a extensão de mensagens precisa de comunicar com vários serviços, gerir interações complexas com a lógica ou o utilizador ou manter o estado entre sessões.
• Suporta comandos de ação, comandos de pesquisa e desfraldamento de ligações.

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 submissão da caixa 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. Procura em pacotes NuGet e apresenta os resultados na extensão de mensagens baseada em pesquisa.	View	View	View	View
Pré-visualização da ação da extensão de mensagem	Este exemplo mostra como utilizar a pré-visualização de ações em Extensões de Mensagens com 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 a partir do comando de ação de extensão de mensagem e obter um cartão de lembrete numa data e hora agendadas.	View	View	NA	View
Extensão de mensagem de inventário da Northwind	Este exemplo demonstra como utilizar uma extensão de mensagem do Teams como um plug-in no Microsoft Copilot para Microsoft 365.	NA	View	NA	NA