Atualizar uma mensagem acionável quando o utilizador a abrir

As mensagens acionáveis permitem que os utilizadores realizem ações rápidas numa mensagem de e-mail, muitas vezes com base nos dados apresentados no card. No entanto, por vezes, os dados são alterados após o envio da mensagem acionável. Por exemplo, o seu serviço pode enviar uma mensagem acionável a vários aprovadores pedindo-lhes que aprovem ou rejeitem um pedido. Um aprovador aprova o pedido, 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, pode fornecer um ponto final HTTP para obter um payload de Cartão Adaptável atualizado com as informações mais recentes quando o utilizador abrir o e-mail no Outlook.

Requisitos de registo

Os serviços mensagens acionáveis registados no programador dashboard com o âmbito Utilizadores de Teste ou Organização podem utilizar esta funcionalidade assim que forem aprovados. Se o seu serviço estiver registado no âmbito Global , tem de contactar onboardoam@microsoft.com para ativar esta funcionalidade.

Utilizar autoInvokeAction

Para utilizar esta funcionalidade, o card tem de utilizar o formato cartão ajustável. A propriedade autoInvokeAction é uma propriedade específica do Outlook adicionada ao tipo AdaptiveCard. O valor desta propriedade é uma ação Action.Http com o method conjunto como POST. A url propriedade especifica um ponto final da API Web no seu serviço que irá fornecer o payload do Cartão Adaptável atualizado.

{
  "$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"
  }
}

Criar o Cartão Ajustável inicial

Ao utilizar autoInvokeAction, é muito importante que os card iniciais incluídos na mensagem continuem a ser valiosos para o utilizador final e, idealmente, sejam acionáveis. O autoInvokeAction pode falhar ou as condições de rede podem adiá-lo, caso em que a card inicial é tudo o que o utilizador final verá.

• Não envie uma card inicial vazia com apenas um autoInvokeAction. Estes cartões serão rejeitados pela plataforma Mensagens Acionáveis.
• Não envie uma card inicial que seja apenas um marcador de posição a pedir ao utilizador para aguardar.
• Envie uma card inicial que apresenta as informações no estado atual, mesmo que isso signifique que o utilizador poderá ver dados desatualizados quando abrir a 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 final para esta ação, veja Implementar a API Web.

O ponto final de um autoInvokeAction também tem de cumprir os seguintes requisitos adicionais.

• Os pedidos têm de ser devolvidos dentro de 2 segundos.
• Os pedidos que demorarem mais tempo serão ignorados pelo cliente e o card original continuará a ser apresentado. A mensagem continuará a ser atualizada no servidor.
• As respostas bem-sucedidas devem incluir um CARD-UPDATE-IN-BODY cabeçalho com valor true e um payload JSON de Cartão Ajustável.

Após o êxito, o Cartão Ajustável devolvido substituirá completamente o card existente na mensagem de e-mail. Se o URL devolver um erro ou exceder o limite de tempo, a card existente continuará a ser apresentada.

Cenário de aprovação de exemplo

Considere este exemplo de pedido de férias card gerado por uma ferramenta de pedido de saída e enviado para o gestor do funcionário.

O card inclui informações para ajudar o gestor a tomar uma decisão, incluindo as datas pedidas e a quantidade de licença restante do funcionário. Estas informações eram precisas quando a mensagem era gerada e enviada. No entanto, os dados podem ser alterados antes de o gestor verificar o e-mail. Por exemplo, o funcionário pode editar o pedido na ferramenta de pedido de saída para alterar as datas pedidas.

Ao incluir uma autoInvokeAction propriedade na mensagem acionável gerada pela ferramenta, a sua card com os dados originais é substituída por um novo card por novos dados quando o gestor os abre. O URL especificado no autoInvokeAction devolve o mesmo payload JSON, com novos valores para as datas de férias pedidas.