Atualizar uma mensagem acionável quando o usuário abri-la

Importante

A integração de novos provedores de Mensagens Acionáveis com um escopo Global está temporariamente pausada até 30 de junho de 2024 devido a atualizações de serviço. Os provedores de escopo global existentes e a integração de provedores de escopo de organização e teste não são afetados. Para obter mais detalhes, confira Perguntas frequentes para Mensagens Acionáveis.

Mensagens acionáveis permitem que os usuários tomem ações rápidas em uma mensagem de email, muitas vezes com base nos dados apresentados no cartão. No entanto, às vezes, os dados são alterados após o envio da mensagem acionável. Por exemplo, seu serviço pode enviar uma mensagem acionável para vários aprovadores pedindo que eles aprovem ou rejeitem uma solicitação. Um aprovador aprova a solicitação, mas a mensagem acionável na caixa de correio do outro aprovador ainda pede aprovação. Agora, com a autoInvokeAction propriedade em mensagens acionáveis, você pode fornecer um ponto de extremidade HTTP para recuperar um conteúdo atualizado do Cartão Adaptável com as informações mais recentes quando o usuário abrir o email no Outlook.

Importante

Atualizar a mensagem acionável quando o usuário abre tem um impacto direto no desempenho percebido da sua solução de mensagem acionável. É crucial que o serviço que fornece o cartão atualizado atenda aos requisitos de desempenho descritos na implementação da API Web.

Requisitos de registro

Os serviços de Mensagens Acionáveis registrados no desenvolvedor dashboard com o escopo Usuários de Teste ou Organização podem usar esse recurso assim que forem aprovados. Se o serviço estiver registrado com o escopo Global , você deverá entrar em contato onboardoam@microsoft.com para habilitar esse recurso.

Usando autoInvokeAction

Para usar esse recurso, seu cartão deve usar o formato Cartão Adaptável. A propriedade autoInvokeAction é uma propriedade específica do Outlook adicionada ao tipo AdaptiveCard. O valor dessa propriedade é uma ação Action.Http com o method definido como POST. A url propriedade especifica um ponto de extremidade da API Web em seu serviço que fornecerá o conteúdo atualizado do Cartão Adaptável.

{
  "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
  "type": "AdaptiveCard",
  "version": "1.0",
  "body": [...],
  "actions": [...],
  "autoInvokeAction": {
    "method": "POST",
    "url": "https://actionablemessages.contoso.com/api/getupdatedcard",
    "body": "",
    "type": "Action.Http"
  }
}

Criando o cartão adaptável inicial

Ao usar autoInvokeAction, é muito importante que o cartão inicial incluído com a mensagem ainda seja valioso para o usuário final e, idealmente, seja acionável. O autoInvokeAction pode falhar ou as condições de rede podem retardá-lo, nesse caso, o cartão inicial é tudo o que o usuário final verá.

• Não envie um cartão inicial vazio com apenas um autoInvokeAction. Esses cartões serão rejeitados pela plataforma Mensagem Acionável.
• Não envie um cartão inicial que seja apenas um espaço reservado solicitando que o usuário aguarde.
• Envie uma cartão inicial que apresente as informações em seu estado atual, mesmo que isso signifique que o usuário poderá ver dados desatualizados no momento em que abrir sua mensagem.

Implementar a API da Web

A Action.Http ação especificada na autoInvokeAction propriedade funciona exatamente da mesma forma que qualquer outra Action.Http ação. Para obter detalhes sobre como implementar o ponto de extremidade dessa ação, consulte Implementando a API Web.

O ponto de extremidade de um autoInvokeAction também deve atender aos seguintes requisitos adicionais.

• As solicitações devem retornar dentro de 2 segundos.
• As solicitações que demoram mais serão ignoradas pelo cliente e as cartão originais continuarão a ser exibidas. A mensagem ainda será atualizada no servidor.
• As respostas bem-sucedidas devem incluir um CARD-UPDATE-IN-BODY cabeçalho com valor true e uma carga JSON de cartão adaptável.

Com êxito, o Cartão Adaptável retornado substituirá completamente o cartão existente na mensagem de email. Se a URL retornar um erro ou um tempo limite, o cartão existente continuará a ser exibido.

Cenário de aprovação de exemplo

Considere este exemplo de solicitação de férias cartão gerada por uma ferramenta de solicitação de licença e enviada ao gerente do funcionário.

Dica

Você pode acessar o JSON e modificar esse exemplo de cartão selecionando o exemplo aprovação de férias no Designer mensagem acionável.

O cartão inclui informações para ajudar o gerente a tomar uma decisão, incluindo as datas solicitadas e a quantidade de licença que o funcionário tem restante. Essas informações foram precisas quando a mensagem foi gerada e enviada. No entanto, os dados podem ser alterados antes que o gerente verifique seu email. Por exemplo, o funcionário pode editar sua solicitação na ferramenta de solicitação de licença para alterar as datas solicitadas.

Ao incluir uma autoInvokeAction propriedade na mensagem acionável gerada pela ferramenta, seu cartão com os dados originais é substituído por um novo cartão com novos dados quando o gerenciador os abre. A URL especificada no autoInvokeAction retorna o mesmo conteúdo JSON, com novos valores para as datas de férias solicitadas.