Actualizar un mensaje accionable cuando el usuario lo abra

Los mensajes accionables permiten a los usuarios realizar acciones rápidas en un mensaje de correo electrónico, a menudo en función de los datos presentados en la tarjeta. Sin embargo, a veces los datos cambian después de que se haya enviado el mensaje accionable. Por ejemplo, el servicio podría enviar un mensaje accionable a varios aprobadores pidiéndoles que aprueben o rechacen una solicitud. Un aprobador aprueba la solicitud, pero el mensaje accionable en el buzón del otro aprobador sigue solicitando aprobación. Ahora, con la autoInvokeAction propiedad en mensajes accionables, puede proporcionar un punto de conexión HTTP para recuperar una carga actualizada de tarjeta adaptable con la información más reciente cuando el usuario abre el correo electrónico en Outlook.

Importante

Actualizar el mensaje accionable cuando el usuario lo abre tiene un impacto directo en el rendimiento percibido de la solución de mensajes accionables. Es fundamental que el servicio que proporciona la tarjeta actualizada cumpla los requisitos de rendimiento descritos en Implementación de la API web.

Requisitos de registro

Los servicios de mensajes accionables registrados en el panel del desarrollador con el ámbito Usuarios de prueba u Organización pueden usar esta característica tan pronto como se aprueben. Si el servicio está registrado con el ámbito global , debe ponerse en contacto con onboardoam@microsoft.com para habilitar esta característica.

Uso de autoInvokeAction

Para usar esta característica, la tarjeta debe usar el formato de tarjeta adaptable . La propiedad autoInvokeAction es una propiedad específica de Outlook agregada al tipo AdaptiveCard. El valor de esta propiedad es una acción Action.Http con el method valor establecido en POST. La url propiedad especifica un punto de conexión de API web en el servicio que proporcionará la carga actualizada de la tarjeta adaptable.

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

Creación de la tarjeta adaptable inicial

Cuando se usa autoInvokeAction, es muy importante que la tarjeta inicial incluida en el mensaje siga siendo valiosa para el usuario final y, idealmente, sea accionable. Es autoInvokeAction posible que se produzca un error o que las condiciones de red lo ralenticen, en cuyo caso la tarjeta inicial es todo lo que verá el usuario final.

• No envíe una tarjeta inicial vacía con solo un autoInvokeAction. Dichas tarjetas serán rechazadas por la plataforma de mensajes accionables.
• No envíe una tarjeta inicial que sea solo un marcador de posición que pida al usuario que espere.
• Envíe una tarjeta inicial que presente la información en su estado actual, incluso si eso significa que el usuario podría ver datos obsoletos en el momento en que abre el mensaje.

Implementación de la API web

La Action.Http acción especificada en la autoInvokeAction propiedad funciona exactamente igual que cualquier otra Action.Http acción. Para obtener más información sobre cómo implementar el punto de conexión para esta acción, consulte Implementación de la API web.

El punto de conexión de debe autoInvokeAction cumplir también los siguientes requisitos adicionales.

• Las solicitudes deben devolverse en un plazo de 2 segundos.
• El cliente omitirá las solicitudes que tardan más tiempo y la tarjeta original seguirá mostrándose. El mensaje se seguirá actualizando en el servidor.
• Las respuestas correctas deben incluir un CARD-UPDATE-IN-BODY encabezado con valor true y una carga JSON de tarjeta adaptable.

Si se ejecuta correctamente, la tarjeta adaptable devuelta reemplazará por completo la tarjeta existente en el mensaje de correo electrónico. Si la dirección URL devuelve un error o agota el tiempo de espera, la tarjeta existente seguirá mostrándose.

Escenario de aprobación de ejemplo

Considere este ejemplo de tarjeta de solicitud de vacaciones generada por una herramienta de solicitud de licencia y enviada al administrador del empleado.

Sugerencia

Para obtener acceso al código JSON y modificar este ejemplo de tarjeta, seleccione el ejemplo Aprobación de vacaciones en el Diseñador de mensajes accionables.

La tarjeta incluye información para ayudar al administrador a tomar una decisión, incluidas las fechas solicitadas y la cantidad de permisos restantes del empleado. Esta información era precisa cuando se generó y envió el mensaje. Sin embargo, los datos podrían cambiar antes de que el administrador compruebe su correo electrónico. Por ejemplo, el empleado podría editar su solicitud en la herramienta de solicitud de permiso para cambiar las fechas solicitadas.

Al incluir una autoInvokeAction propiedad en el mensaje accionable generado por la herramienta, la tarjeta con los datos originales se reemplaza por una nueva tarjeta con nuevos datos cuando el administrador la abre. La dirección URL especificada en autoInvokeAction devuelve la misma carga JSON, con nuevos valores para las fechas de vacaciones solicitadas.