Déclencheur Lambda message personnalisé

Lorsque vous disposez d'une norme externe pour les e-mails et les SMS messages que vous souhaitez envoyer à vos utilisateurs, ou lorsque vous souhaitez appliquer votre propre logique au moment de l'exécution au formatage des messages utilisateur, ajoutez un déclencheur de message personnalisé à votre groupe d'utilisateurs. Le message personnalisé Lambda reçoit le contenu de tous les e-mails et SMS messages avant que votre groupe d'utilisateurs ne les envoie. Votre fonction Lambda a alors la possibilité de modifier le contenu et l'objet du message.

Amazon Cognito invoque ce déclencheur avant d'envoyer un e-mail ou un message de vérification par téléphone ou un code d'authentification multifactorielle (). MFA Vous pouvez personnaliser le message de manière dynamique avec votre déclencheur de message personnalisé. Vous pouvez modifier les messages personnalisés statiques sous l'onglet Message Customizations (Personnalisation des messages) de la console Amazon Cognito.

La demande inclut codeParameter. Il s'agit d'une chaîne qui sert d'espace réservé pour le code remis par Amazon Cognito à l'utilisateur. Insérez la chaîne codeParameter dans le corps du message, à l'emplacement où vous souhaitez que le code de vérification apparaisse. Quand il reçoit cette réponse, Amazon Cognito remplace la chaîne codeParameter par le code de vérification réel.

Note

Une fonction Lambda de message personnalisé avec la source du déclencheur CustomMessage_AdminCreateUser renvoie un nom d'utilisateur et un code de vérification. Étant donné qu'un utilisateur créé par l'administrateur doit recevoir à la fois son nom d'utilisateur et son code, la réponse de votre fonction doit inclure à la fois request.usernameParameter et request.codeParameter.

Sources du déclencheur Lambda message personnalisé

triggerSource valeur	Événement
CustomMessage_SignUp	Message personnalisé – Pour envoyer le code de confirmation après l'inscription.
CustomMessage_AdminCreateUser	Message personnalisé – Pour envoyer le mot de passe temporaire à un nouvel utilisateur.
CustomMessage_ResendCode	Message personnalisé – Pour renvoyer le code de confirmation à un utilisateur existant.
CustomMessage_ForgotPassword	Message personnalisé – Pour envoyer le code de confirmation suite à une demande de mot de passe oublié.
CustomMessage_UpdateUserAttribute	Message personnalisé – En cas de modification de l'e-mail ou du numéro de téléphone, ce déclencheur envoie automatiquement un code de vérification à l'utilisateur. Impossible à utiliser pour d'autres attributs.
CustomMessage_VerifyUserAttribute	Message personnalisé – Ce déclencheur envoie un code de vérification à l'utilisateur lorsque ce dernier en fait manuellement la demande concernant une nouvelle adresse e-mail ou un nouveau numéro de téléphone.
CustomMessage_Authentication	Message personnalisé : pour envoyer MFA du code lors de l'authentification.

Paramètres du déclencheur Lambda message personnalisé

La demande qu'Amazon Cognito transmet à cette fonction Lambda est une combinaison des paramètres ci-dessous et des paramètres courants qu'Amazon Cognito ajoute à toutes les demandes.

JSON

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

Paramètres de demande de message personnalisé

userAttributes

Une ou plusieurs paires nom-valeur représentant des attributs utilisateur.

codeParameter

Chaîne que vous pouvez utiliser comme espace réservé pour le code de vérification dans le message personnalisé.

usernameParameter

Nom de l'utilisateur. Amazon Cognito inclut ce paramètre dans les demandes provenant d'utilisateurs créés par l'administrateur.

clientMetadata

Une ou plusieurs paires clé-valeur que vous pouvez fournir en tant qu'entrée personnalisée à la fonction Lambda que vous spécifiez pour le déclencheur de message personnalisé. La demande qui invoque une fonction de message personnalisée n'inclut pas les données transmises dans le ClientMetadata paramètre in AdminInitiateAuthand InitiateAuthAPIoperations. Pour transmettre ces données à votre fonction Lambda, vous pouvez utiliser le ClientMetadata paramètre dans les actions suivantes : API

• AdminResetUserPassword

• AdminRespondToAuthChallenge

• AdminUpdateUserAttributes

• ForgotPassword

• GetUserAttributeVerificationCode

• ResendConfirmationCode

• SignUp

• UpdateUserAttributes

Paramètres de réponse de message personnalisé

Dans la réponse, spécifiez le texte personnalisé à utiliser dans les messages à vos utilisateurs. Pour connaître les contraintes de chaîne appliquées par Amazon Cognito à ces paramètres, consultez. MessageTemplateType

smsMessage

Le SMS message personnalisé à envoyer à vos utilisateurs. Il doit inclure la valeur codeParameter que vous avez reçue dans la demande.

emailMessage

Message électronique personnalisé à envoyer à vos utilisateurs. Vous pouvez utiliser le HTML formatage dans le emailMessage paramètre. Il doit inclure la valeur codeParameter que vous avez reçue dans la demande en tant que variable {####}. Amazon Cognito peut utiliser le paramètre emailMessage seulement si l'attribut EmailSendingAccount du groupe d'utilisateurs est DEVELOPER. Si l'attribut EmailSendingAccount du groupe d'utilisateurs n'est pas DEVELOPER et qu'un paramètre emailMessage est renvoyé, Amazon Cognito génère un code d'erreur 400 com.amazonaws.cognito.identity.idp.model.InvalidLambdaResponseException. Lorsque vous choisissez Amazon Simple Email Service (AmazonSES) pour envoyer des e-mails, l'EmailSendingAccountattribut d'un groupe d'utilisateurs estDEVELOPER. Sinon, la valeur est COGNITO_DEFAULT.

emailSubject

Ligne d'objet pour le message personnalisé. Vous ne pouvez utiliser le emailSubject paramètre que si l' EmailSendingAccountattribut du groupe d'utilisateurs estDEVELOPER. Si l'attribut EmailSendingAccount du groupe d'utilisateurs n'est pas DEVELOPER et qu'Amazon Cognito renvoie un paramètre emailSubject, Amazon Cognito génère un code d'erreur 400 com.amazonaws.cognito.identity.idp.model.InvalidLambdaResponseException. L'EmailSendingAccountattribut d'un groupe d'utilisateurs est DEVELOPER lorsque vous choisissez d'utiliser Amazon Simple Email Service (AmazonSES) pour envoyer des e-mails. Sinon, la valeur est COGNITO_DEFAULT.

Exemple de message personnalisé pour l'inscription

Cet exemple de fonction Lambda personnalise un e-mail ou un SMS message lorsque le service nécessite qu'une application envoie un code de vérification à l'utilisateur.

Amazon Cognito peut appeler un déclencheur Lambda lors de plusieurs événements : après l'inscription, lors du renvoi d'un code de vérification, lors de la récupération d'un mot de passe oublié ou lors de la vérification d'un attribut utilisateur. La réponse inclut des messages pour les deux SMS et un e-mail. Le message doit inclure le paramètre de code "####". Ce paramètre est l'espace réservé pour le code de vérification que l'utilisateur reçoit.

La longueur maximale d'un message électronique est de 20 000 UTF à 8 caractères. Cette longueur inclut le code de vérification. Vous pouvez utiliser des HTML balises dans ces e-mails.

La longueur maximale des SMS messages est de 140 UTF à 8 caractères. Cette longueur inclut le code de vérification.

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 transmet les informations d’événement à votre fonction Lambda. Cette fonction renvoie alors le même objet d’événement à Amazon Cognito, avec d’éventuelles modifications dans la réponse. Dans la console Lambda, vous pouvez configurer un événement de test avec des données pertinentes pour votre déclencheur Lambda. Voici un événement de test pour cet exemple de code :

JSON

{
	"version": "1",
	"region": "us-west-2",
	"userPoolId": "us-west-2_EXAMPLE",
	"userName": "test-user",
	"callerContext": {
		"awsSdkVersion": "aws-sdk-unknown-unknown",
		"clientId": "1example23456789"
	},
	"triggerSource": "CustomMessage_SignUp",
	"request": {
		"userAttributes": {
			"sub": "a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
			"cognito:user_status": "CONFIRMED",
			"email_verified": "true",
			"phone_number_verified": "true",
			"phone_number": "[phone]",
			"email": "[e-mail]"
		},
		"codeParameter": "{####}",
		"linkParameter": "{##Click Here##}",
		"usernameParameter": "None"
	},
	"response": {
		"smsMessage": "None",
		"emailMessage": "None",
		"emailSubject": "None"
	}
}

Exemple de message personnalisé pour la création d'utilisateurs par les administrateurs

La demande envoyée par Amazon Cognito à cet exemple de fonction Lambda de message personnalisé comporte une triggerSource valeur, un nom d'utilisateur CustomMessage_AdminCreateUser et un mot de passe temporaire. La fonction est renseignée ${event.request.codeParameter} à partir du mot de passe temporaire de la demande et ${event.request.usernameParameter} du nom d'utilisateur de la demande.

Vos messages personnalisés doivent insérer les valeurs de codeParameter et usernameParameter dans smsMessage et emailMessage dans l'objet de réponse. Dans cet exemple, la fonction écrit le même message dans les champs de réponse event.response.smsMessage etevent.response.emailMessage.

La longueur maximale d'un message électronique est de 20 000 UTF à 8 caractères. Cette longueur inclut le code de vérification. Vous pouvez utiliser des HTML tags dans ces e-mails. La longueur maximale des SMS messages est de 140 UTF à 8 caractères. Cette longueur inclut le code de vérification.

La réponse inclut des messages pour les deux SMS et un e-mail.

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 transmet les informations d’événement à votre fonction Lambda. Cette fonction renvoie alors le même objet d’événement à Amazon Cognito, avec d’éventuelles modifications dans la réponse. Dans la console Lambda, vous pouvez configurer un événement de test avec des données pertinentes pour votre déclencheur Lambda. Voici un événement de test pour cet exemple de code :

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