Desencadenador de Lambda para mensajes personalizados - Amazon Cognito
Orígenes del disparador de mensajes personalizadosParámetros de desencadenadores de Lambda para mensajes personalizadosEjemplo de mensaje personalizado para registrarseEjemplo de mensaje personalizado para la creación de usuarios por parte del administrador

Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.

Desencadenador de Lambda para mensajes personalizados

Amazon Cognito llama a este desencadenador antes de enviar un mensaje de verificación por teléfono o correo electrónico, o un código de autenticación multifactor (MFA, por sus siglas en inglés). Puede personalizar el mensaje dinámicamente con el desencadenador de mensajes personalizado. Los mensajes personalizados estáticos se pueden editar en la pestaña Message Customizations (Personalizaciones de mensajes) de la consola de Amazon Cognito original.

La solicitud incluye codeParameter. Esta es una cadena que actúa de marcador de posición del código que Amazon Cognito entrega al usuario. Especifique la cadena codeParameter en el cuerpo del mensaje, en el lugar donde desea que se inserte el código de verificación. Cuando Amazon Cognito recibe esta respuesta, reemplaza la cadena codeParameter por el código de verificación real.

nota

Una función de Lambda para mensajes personalizados con el desencadenador de origen CustomMessage_AdminCreateUser devuelve un nombre de usuario y un código de verificación. Como un usuario creado por un administrador debe recibir tanto su nombre de usuario como su código, la respuesta de la función debe incluir tanto request.usernameParameter como request.codeParameter.

Fuentes de desencadenadores de Lambda para mensajes personalizados

Valor de triggerSource Evento
CustomMessage_SignUp Mensaje personalizado para enviar el código de confirmación posterior a la inscripción.
CustomMessage_AdminCreateUser Mensaje personalizado para enviar la contraseña temporal a un usuario nuevo.
CustomMessage_ResendCode Mensaje personalizado para volver a enviar el código de confirmación a un usuario ya existente.
CustomMessage_ForgotPassword Mensaje personalizado para enviar el código de confirmación a una solicitud de contraseña olvidada.
CustomMessage_UpdateUserAttribute Mensaje personalizado: cuando el correo electrónico o el número de teléfono de un usuario cambia, este disparador envía automáticamente un código de verificación al usuario. No se puede utilizar para otros atributos.
CustomMessage_VerifyUserAttribute Mensaje personalizado: este disparador envía un código de verificación al usuario cuando este lo solicita manualmente para un correo electrónico o un número de teléfono nuevo.
CustomMessage_Authentication Mensaje personalizado para enviar código de MFA durante la autenticación.

Parámetros de desencadenadores de Lambda para mensajes personalizados

La solicitud que Amazon Cognito envía a esta función de Lambda es una combinación de los parámetros que se indican a continuación y los parámetros comunes que Amazon Cognito agrega a todas las solicitudes.

JSON
{
    "request": {
        "userAttributes": {
            "string": "string",
            . . .
        }
        "codeParameter": "####",
        "usernameParameter": "string",
        "clientMetadata": {
            "string": "string",
            . . .
        }
    },
    "response": {
        "smsMessage": "string",
        "emailMessage": "string",
        "emailSubject": "string"
    }
}

Parámetros de la solicitud para mensajes personalizados

userAttributes

Uno o varios pares de nombre y valor que representan atributos de usuario.

codeParameter

Cadena que se usa como marcador de posición del código de verificación en los mensajes personalizados.

Parámetrousername

El nombre de usuario. Amazon Cognito incluye este parámetro en las solicitudes que provienen de los usuarios creados por el administrador.

clientMetadata

Uno o varios pares de clave-valor que puede proporcionar como datos de entrada personalizados a la función de Lambda que especifica destinada al desencadenador para mensajes personalizados. La solicitud que invoca una función de mensaje personalizada no incluye los datos transferidos en el ClientMetadata parámetro en AdminInitiateAuthlas operaciones de InitiateAuthAPI. Para pasar estos datos a la función Lambda, puede usar el ClientMetadata parámetro en las siguientes acciones de la API:

Parámetros de la respuesta para mensajes personalizados

En la respuesta, especifique el texto personalizado que usará en los mensajes a los usuarios. Para ver las restricciones de cadena que Amazon Cognito aplica a estos parámetros, consulte. MessageTemplateType

smsMessage

El mensaje de texto SMS personalizado que se envía a los usuarios. Debe incluir el valor codeParameter recibido en la solicitud.

emailMessage

Mensaje de correo electrónico personalizado que se envía a los usuarios. Puede utilizar el formato HTML en el parámetro emailMessage. Debe incluir el valor codeParameter que ha recibido en la solicitud como variable {####}. Amazon Cognito puede utilizar el parámetro emailMessage solo si el atributo EmailSendingAccount del grupo de usuarios es DEVELOPER. Si el atributo EmailSendingAccount del grupo de usuarios no es DEVELOPER y se devuelve un parámetro emailMessage, Amazon Cognito genera un código de error 400 com.amazonaws.cognito.identity.idp.model.InvalidLambdaResponseException. El atributo EmailSendingAccount de un grupo de usuarios es DEVELOPER cuando elige utilizar Amazon Simple Email Service (Amazon SES) para enviar mensajes de correo electrónico. De lo contrario, el valor es COGNITO_DEFAULT.

emailSubject

La línea de asunto del mensaje personalizado. Solo puede usar el emailSubject parámetro si el EmailSendingAccount atributo del grupo de usuarios esDEVELOPER. Si el atributo EmailSendingAccount del grupo de usuarios no es DEVELOPER y Amazon Cognito devuelve un parámetro emailSubject, Amazon Cognito genera un código de error 400 com.amazonaws.cognito.identity.idp.model.InvalidLambdaResponseException. El atributo EmailSendingAccount de un grupo de usuarios es DEVELOPER cuando elige utilizar Amazon Simple Email Service (Amazon SES) para enviar mensajes de correo electrónico. De lo contrario, el valor es COGNITO_DEFAULT.

Ejemplo de mensaje personalizado para registrarse

Esta función de Lambda personaliza un mensaje de correo electrónico o SMS cuando el servicio necesita que una aplicación envíe un código de verificación al usuario.

Amazon Cognito puede llamar a un desencadenador de Lambda en varios eventos: después del registro, al reenviar un código de verificación, para recuperar una contraseña olvidada o al verificar un atributo de usuario. La respuesta contiene mensajes tanto para SMS como para correo electrónico. El mensaje debe incluir el parámetro de código "####". Este parámetro es el marcador de posición del código de verificación que recibe el usuario.

La longitud máxima de un mensaje de correo electrónico es de 20 000 caracteres UTF-8. Esta longitud incluye el código de verificación. Puede utilizar etiquetas HTML en estos mensajes de correo electrónico.

La longitud máxima de los mensaje SMS es 140 caracteres UTF-8. Esta longitud incluye el código de verificación.

Node.js
const handler = async (event) => {
  if (event.triggerSource === "CustomMessage_SignUp") {
    const message = `Thank you for signing up. Your confirmation code is ${event.request.codeParameter}.`;
    event.response.smsMessage = message;
    event.response.emailMessage = message;
    event.response.emailSubject = "Welcome to the service.";
  }
  return event;
};

export { handler };

Amazon Cognito transfiere la información del evento a la función de Lambda. A continuación, la función devuelve el mismo objeto de evento a Amazon Cognito con los cambios en la respuesta. En la consola de Lambda puede configurar un evento de prueba con los datos relevantes para el desencadenador de Lambda. El siguiente es un evento de prueba para este código de ejemplo:

JSON
{
  "version": 1,
  "triggerSource": "CustomMessage_SignUp/CustomMessage_ResendCode/CustomMessage_ForgotPassword/CustomMessage_VerifyUserAttribute",
  "region": "<region>",
  "userPoolId": "<userPoolId>",
  "userName": "<userName>",
  "callerContext": {
      "awsSdk": "<calling aws sdk with version>",
      "clientId": "<apps client id>",
      ...
  },
  "request": {
      "userAttributes": {
          "phone_number_verified": false,
          "email_verified": true,
           ...
      },
      "codeParameter": "####"
  },
  "response": {
      "smsMessage": "<custom message to be sent in the message with code parameter>"
      "emailMessage": "<custom message to be sent in the message with code parameter>"
      "emailSubject": "<custom email subject>"
  }
}

Ejemplo de mensaje personalizado para la creación de usuarios por parte del administrador

La solicitud que Amazon Cognito envió a este ejemplo de función Lambda de mensajes personalizados tiene un triggerSource valor de, un nombre de usuario CustomMessage_AdminCreateUser y una contraseña temporal. La función se completa con la contraseña temporal ${event.request.codeParameter} de la solicitud y con el nombre de usuario ${event.request.usernameParameter} de la solicitud.

Los mensajes personalizados deben insertar los valores de codeParameter smsMessage y usernameParameter dentro del objeto emailMessage de respuesta. En este ejemplo, la función escribe el mismo mensaje en los campos de respuesta event.response.smsMessage yevent.response.emailMessage.

La longitud máxima de un mensaje de correo electrónico es de 20 000 caracteres UTF-8. Esta longitud incluye el código de verificación. Puede usar etiquetas HTML en estos correos electrónicos. La longitud máxima de los mensaje SMS es 140 caracteres UTF-8. Esta longitud incluye el código de verificación.

La respuesta contiene mensajes tanto para SMS como para correo electrónico.

Node.js
const handler = async (event) => {
  if (event.triggerSource === "CustomMessage_AdminCreateUser") {
    const message = `Welcome to the service. Your user name is ${event.request.usernameParameter}. Your temporary password is ${event.request.codeParameter}`;
    event.response.smsMessage = message;
    event.response.emailMessage = message;
    event.response.emailSubject = "Welcome to the service";
  }
  return event;
};

export { handler }

Amazon Cognito transfiere la información del evento a la función de Lambda. A continuación, la función devuelve el mismo objeto de evento a Amazon Cognito con los cambios en la respuesta. En la consola de Lambda puede configurar un evento de prueba con los datos relevantes para el desencadenador de Lambda. El siguiente es un evento de prueba para este código de ejemplo:

JSON
{
  "version": 1,
  "triggerSource": "CustomMessage_AdminCreateUser",
  "region": "<region>",
  "userPoolId": "<userPoolId>",
  "userName": "<userName>",
  "callerContext": {
      "awsSdk": "<calling aws sdk with version>",
      "clientId": "<apps client id>",
      ...
  },
  "request": {
      "userAttributes": {
          "phone_number_verified": false,
          "email_verified": true,
           ...
      },
      "codeParameter": "####",
      "usernameParameter": "username"
  },
  "response": {
      "smsMessage": "<custom message to be sent in the message with code parameter and username parameter>"
      "emailMessage": "<custom message to be sent in the message with code parameter and username parameter>"
      "emailSubject": "<custom email subject>"
  }
}