Adaptive Cards no Teams: workshop para transformar uma notificação em interação

Toda notificação no Teams começa com uma boa intenção: avisar alguém de que algo aconteceu. O problema é que, na prática, a maioria das notificações entrega só o aviso. A pessoa lê, abre outro app pra agir, volta, e o contexto já era. Adaptive Cards mudam esse fluxo. Eles trazem a ação para dentro do cartão, no próprio chat ou canal.

Neste workshop, você vai substituir uma notificação comum por um Adaptive Card interativo usando Power Automate. O cenário é um app de ideias dos funcionários, mas o padrão serve para qualquer processo que hoje dispara um texto e espera que alguém faça algo com ele.

A página de partida para este conteúdo foi o artigo "Replace notification with adaptive card to increase collaboration" no Microsoft Learn, que documenta o cenário completo com o app Employee Ideas. Complementei com a visão geral dos Adaptive Cards e o tutorial de criação do primeiro cartão, ambos da documentação oficial.

O que é um Adaptive CardLink para esta seção

Adaptive Cards são blocos de informação que você escreve em JSON e que, ao chegar num host como o Teams, se transformam em interface nativa, sem CSS, sem HTML, sem surpresa de renderização. Como eles se adaptam ao host, funcionam como veículo para compartilhar informação entre o Teams e outros serviços.

No Power Automate, você tem ações específicas para publicar Adaptive Cards no Teams. Elas se dividem em dois grupos: as que só mostram informação (com botões do tipo OpenURL) e as que esperam resposta (com botões do tipo Action.Submit). A diferença é crucial: se você quer coletar dados, precisa da ação que tem "and wait for a response" no nome. Sem ela, qualquer clique num botão de submissão devolve erro.

O que você vai construirLink para esta seção

Vou usar o exemplo do app Employee Ideas, que vem como template de amostra da Microsoft para Teams. Hoje, quando um funcionário submete uma ideia, o app envia uma notificação em HTML para o canal. A pessoa que recebe precisa clicar, abrir o app, navegar até o registro e só então agir. Nosso objetivo é substituir essa mensagem por um Adaptive Card que:

• Mostra o título da ideia e a campanha associada
• Inclui um botão "View" que leva direto ao registro
• Dispara tudo por um fluxo do Power Automate, sem código novo no app

Pré-requisitosLink para esta seção

• Microsoft Teams com o app Workflows instalado
• O app Employee Ideas instalado num time do Teams
• Acesso ao Power Automate (make.powerautomate.com) no ambiente correto do time

No seu inquilino, confirme que o app Workflows está disponível antes de começar. Sem ele, as ações de Adaptive Card no Power Automate retornam erro.

Passo a passoLink para esta seção

1. Crie o fluxo no Power AutomateLink para esta seção

Abra o Power Apps for Teams, localize o app Employee Ideas e, no menu de reticências, selecione Power Automate. Escolha "Create a new flow". O Power Automate Studio abre numa janela separada. Verifique se o ambiente exibido no canto superior corresponde ao time onde o app está instalado.

Nomeie o fluxo como "Employee Ideas Adaptive Card To Teams".

Adicione o gatilho Power Apps. Ele permite que o app passe dados para o fluxo. Em seguida, adicione a ação "Get a row by ID" do Dataverse. No campo Row ID, selecione "Ask in Power Apps" no menu de conteúdo dinâmico. Isso cria uma variável no gatilho.

2. Configure as variáveisLink para esta seção

Adicione três ações "Initialize variable":

• varCardTitle (String), recebe o título da ideia
• varCampaign (String), recebe o nome da campanha
• varReviewIdeasLink (String), recebe o link decodificado para o registro

Para o link, copie a URL da guia onde o app está instalado no Teams. Use um decodificador de URL para extrair o contexto. O resultado vai alimentar o botão de navegação no cartão.

3. Monte o JSON do Adaptive CardLink para esta seção

Adicione uma ação "Compose" com a função replace para sanitizar o link. Depois, adicione a ação "Post adaptive card in a chat or channel". Configure:

• Post as: User
• Post in: Channel
• Team e Channel: selecione onde o cartão deve aparecer

No campo Adaptive Card, cole o JSON do cartão. O exemplo da documentação usa três TextBlocks (título, mensagem de nova ideia, nome da campanha) e um botão Action.OpenUrl que leva ao registro. As variáveis do Power Automate entram com a sintaxe @{variables('nome')}.

No campo Subject, use algo como "New idea submitted for @{variables('varCampaign')} Campaign", isso vira o assunto da mensagem no canal.

4. Conecte o fluxo ao appLink para esta seção

Volte ao Power Apps Studio. No botão de submissão da ideia (btnCampaignIdeaControls_Submit), a propriedade OnSelect contém o código original que envia a notificação HTML. Copie esse código para um editor de texto, remova o bloco MicrosoftTeams.PostMessageToChannelV3 e substitua pela chamada ao fluxo:

EmployeeIdeasAdaptiveCardToTeams.Run(locFormRecordIdea.Title, gblSelectedRecordCampaign.Title, locFormRecordIdea.'Employee Idea', locFormRecordIdea.'Employee Idea')

Cole o código editado de volta no OnSelect. Verifique se não há erros.

5. Ajuste o deep linkingLink para esta seção

O Adaptive Card tem um link que leva de volta ao registro. Para que o app abra na tela certa, edite a tela de carregamento (Loading screen). No temporizador tmrLoadingDelay, propriedade OnTimerEnd, substitua o IF condicional por uma versão que verifica o parâmetro subEntityId. Se ele existir, o app carrega os dados do registro específico e navega direto para ele. Senão, segue o fluxo normal de entrada.

6. Publique e testeLink para esta seção

No Power Apps Studio, selecione "Publish to Teams". Depois, no Teams, navegue até o canal, submeta uma ideia e veja o Adaptive Card aparecer. Clique no link do cartão e confirme que o registro abre direto.

Problemas comunsLink para esta seção

O fluxo dá erro na execução. Verifique se o app Workflows está instalado no Teams. JSON mal formatado também causa erro, aspas curvas em vez de retas, ou valores de texto sem aspas duplas. Use o Card Payload Editor em adaptivecards.io/designer para validar.

O cartão aparece mas o botão não funciona. Se a ação do fluxo não tiver "and wait for a response" no nome, apenas botões OpenURL funcionam. Botões Action.Submit retornam erro.

O cartão some depois do primeiro clique. Adaptive Cards criados com "wait for a response" aceitam uma única submissão. Depois disso, o fluxo continua e cliques adicionais são ignorados. Configure o campo "Update message" para exibir um cartão de substituição, isso avisa quem respondeu que o formulário já foi processado e impede tentativas repetidas.

A imagem no cartão não aparece. Todo valor de imagem num Adaptive Card precisa ser uma URL válida. Não é possível incorporar o conteúdo da imagem diretamente. Teste a URL num navegador antes de colocar no JSON.

E depoisLink para esta seção

O exemplo do Employee Ideas usa um app Power Apps como origem, mas o padrão funciona com qualquer gatilho que o Power Automate suporte: um formulário do SharePoint, um registro novo no Dataverse, um email, até um webhook. O que muda é de onde vêm os dados que preenchem as variáveis do JSON.

Se o seu cenário não precisa de formulário, apenas de informação, use a ação "Post your own adaptive card as the flow bot to a channel", ela não espera resposta e serve para alertas, atualizações de metadados e notificações de status.

E se você prefere desenhar o cartão visualmente em vez de escrever JSON, o Adaptive Cards Designer em adaptivecards.io/designer oferece um editor de arrastar e soltar. O designer exporta o JSON pronto para colar no fluxo.

ReferênciasLink para esta seção

• Visão geral de Adaptive Cards para Microsoft Teams: https://learn.microsoft.com/power-automate/overview-adaptive-cards ((abre em nova aba))
• Tutorial "Create your first adaptive card": https://learn.microsoft.com/power-automate/create-adaptive-cards ((abre em nova aba))
• Cenário completo "Replace notification with adaptive card to increase collaboration": https://learn.microsoft.com/power-apps/teams/replace-notification-with-adaptive-card ((abre em nova aba))
• Adaptive Cards Designer: https://adaptivecards.io/designer/ ((abre em nova aba))
• Schema de Adaptive Cards: https://adaptivecards.io/explorer/ ((abre em nova aba))