Custom message Lambda trigger - Amazon Cognito (original) (raw)

When you have an external standard for the email and SMS messages that you want to send to your users, or when you want to apply your own logic at runtime to the formatting of user messages, add a custom message trigger to your user pool. The custom message Lambda receives the contents of all email and SMS messages before your user pool sends them. Your Lambda function then has the opportunity to modify the message contents and subject.

Amazon Cognito invokes this trigger before it sends an email or phone verification message or a multi-factor authentication (MFA) code. You can customize the message dynamically with your custom message trigger.

The request includes codeParameter. This is a string that acts as a placeholder for the code that Amazon Cognito delivers to the user. Insert thecodeParameter string into the message body where you want the verification code to appear. When Amazon Cognito receives this response, Amazon Cognito replaces thecodeParameter string with the actual verification code.

Note

The input event for a custom message Lambda function with theCustomMessage_AdminCreateUser trigger source includes a username and verification code. Because an admin-created user must receive both their user name and code, the response from your function must include placeholder variables for the username and code. The placeholders for your message are the values ofrequest.usernameParameter and request.codeParameter. These values are typically {username} and {####}; as a best practice, reference the input values instead of hardcoding the variable names.

Topics

Custom message Lambda trigger sources
Custom message Lambda trigger parameters
Custom message for sign-up example
Custom message for admin create user example

Custom message Lambda trigger sources

triggerSource value	Event
CustomMessage_SignUp	Custom message – To send the confirmation code post sign-up.
CustomMessage_AdminCreateUser	Custom message – To send the temporary password to a new user.
CustomMessage_ResendCode	Custom message – To resend the confirmation code to an existing user.
CustomMessage_ForgotPassword	Custom message – To send the confirmation code for Forgot Password request.
CustomMessage_UpdateUserAttribute	Custom message – When a user's email or phone number is changed, this trigger sends a verification code automatically to the user. Cannot be used for other attributes.
CustomMessage_VerifyUserAttribute	Custom message – This trigger sends a verification code to the user when they manually request it for a new email or phone number.
CustomMessage_Authentication	Custom message – To send MFA code during authentication.

Custom message Lambda trigger parameters

The request that Amazon Cognito passes to this Lambda function is a combination of the parameters below and thecommon parameters that Amazon Cognito adds to all requests.

JSON

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

Custom message request parameters

Custom message response parameters

In the response, specify the custom text to use in messages to your users. For the string constraints that Amazon Cognito applies to these parameters, see MessageTemplateType.

smsMessage

The custom SMS message to be sent to your users. Must include thecodeParameter value that you received in the request.

emailMessage

The custom email message to send to your users. You can use HTML formatting in the emailMessage parameter. Must include thecodeParameter value that you received in the request as the variable {####}. Amazon Cognito can use theemailMessage parameter only if theEmailSendingAccount attribute of the user pool isDEVELOPER. If the EmailSendingAccount attribute of the user pool isn't DEVELOPER and anemailMessage parameter is returned, Amazon Cognito generates a 400 error codecom.amazonaws.cognito.identity.idp.model.InvalidLambdaResponseException. When you choose Amazon Simple Email Service (Amazon SES) to send email messages, theEmailSendingAccount attribute of a user pool isDEVELOPER. Otherwise, the value isCOGNITO_DEFAULT.

emailSubject

The subject line for the custom message. You can only use theemailSubject parameter if the EmailSendingAccount attribute of the user pool is DEVELOPER. If theEmailSendingAccount attribute of the user pool isn'tDEVELOPER and Amazon Cognito returns anemailSubject parameter, Amazon Cognito generates a 400 error codecom.amazonaws.cognito.identity.idp.model.InvalidLambdaResponseException. The EmailSendingAccount attribute of a user pool isDEVELOPER when you choose to use Amazon Simple Email Service (Amazon SES) to send email messages. Otherwise, the value isCOGNITO_DEFAULT.

This example Lambda function customizes an email or SMS message when the service requires an app to send a verification code to the user.

Amazon Cognito can invoke a Lambda trigger at multiple events: post-registration, resending a verification code, recovering a forgotten password, or verifying a user attribute. The response includes messages for both SMS and email. The message must include the code parameter "####". This parameter is the placeholder for the verification code that the user receives.

The maximum length for an email message is 20,000 UTF-8 characters,. This length includes the verification code. You can use HTML tags in these email messages.

The maximum length of SMS messages is 140 UTF-8 characters. This length includes the verification code.

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 passes event information to your Lambda function. The function then returns the same event object to Amazon Cognito, with any changes in the response. In the Lambda console, you can set up a test event with data that is relevant to your Lambda trigger. The following is a test event for this code sample:

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": "+12065551212",
            "email": "test-user@example.com"
        },
        "codeParameter": "{####}",
        "linkParameter": "{##Click Here##}",
        "usernameParameter": "None"
    },
    "response": {
        "smsMessage": "None",
        "emailMessage": "None",
        "emailSubject": "None"
    }
}

Custom message for admin create user example

The request that Amazon Cognito sent to this example custom message Lambda function has atriggerSource value of CustomMessage_AdminCreateUser and a username and temporary password. The function populates${event.request.codeParameter} from the temporary password in the request, and ${event.request.usernameParameter} from the username in the request.

Your custom messages must insert the values of codeParameter andusernameParameter into smsMessage andemailMessage in the response object. In this example, the function writes the same message to the response fields event.response.smsMessage and event.response.emailMessage.

The maximum length of an email message is 20,000 UTF-8 characters. This length includes the verification code. You can use HTML tags in these emails. The maximum length of SMS messages is 140 UTF-8 characters. This length includes the verification code.

The response includes messages for both SMS and email.

Node.js

const handler = async (event) => {
  if (event.triggerSource === "CustomMessage_AdminCreateUser") {
    const message = `Welcome to the service. Your user name is <span class="katex"><span class="katex-mathml"><math xmlns="http://www.w3.org/1998/Math/MathML"><semantics><mrow><mrow><mi>e</mi><mi>v</mi><mi>e</mi><mi>n</mi><mi>t</mi><mi mathvariant="normal">.</mi><mi>r</mi><mi>e</mi><mi>q</mi><mi>u</mi><mi>e</mi><mi>s</mi><mi>t</mi><mi mathvariant="normal">.</mi><mi>u</mi><mi>s</mi><mi>e</mi><mi>r</mi><mi>n</mi><mi>a</mi><mi>m</mi><mi>e</mi><mi>P</mi><mi>a</mi><mi>r</mi><mi>a</mi><mi>m</mi><mi>e</mi><mi>t</mi><mi>e</mi><mi>r</mi></mrow><mi mathvariant="normal">.</mi><mi>Y</mi><mi>o</mi><mi>u</mi><mi>r</mi><mi>t</mi><mi>e</mi><mi>m</mi><mi>p</mi><mi>o</mi><mi>r</mi><mi>a</mi><mi>r</mi><mi>y</mi><mi>p</mi><mi>a</mi><mi>s</mi><mi>s</mi><mi>w</mi><mi>o</mi><mi>r</mi><mi>d</mi><mi>i</mi><mi>s</mi></mrow><annotation encoding="application/x-tex">{event.request.usernameParameter}. Your temporary password is </annotation></semantics></math></span><span class="katex-html" aria-hidden="true"><span class="base"><span class="strut" style="height:0.8889em;vertical-align:-0.1944em;"></span><span class="mord"><span class="mord mathnormal">e</span><span class="mord mathnormal" style="margin-right:0.03588em;">v</span><span class="mord mathnormal">e</span><span class="mord mathnormal">n</span><span class="mord mathnormal">t</span><span class="mord">.</span><span class="mord mathnormal">re</span><span class="mord mathnormal" style="margin-right:0.03588em;">q</span><span class="mord mathnormal">u</span><span class="mord mathnormal">es</span><span class="mord mathnormal">t</span><span class="mord">.</span><span class="mord mathnormal">u</span><span class="mord mathnormal" style="margin-right:0.02778em;">ser</span><span class="mord mathnormal">nam</span><span class="mord mathnormal">e</span><span class="mord mathnormal" style="margin-right:0.13889em;">P</span><span class="mord mathnormal">a</span><span class="mord mathnormal" style="margin-right:0.02778em;">r</span><span class="mord mathnormal">am</span><span class="mord mathnormal">e</span><span class="mord mathnormal">t</span><span class="mord mathnormal" style="margin-right:0.02778em;">er</span></span><span class="mord">.</span><span class="mord mathnormal" style="margin-right:0.22222em;">Y</span><span class="mord mathnormal">o</span><span class="mord mathnormal">u</span><span class="mord mathnormal" style="margin-right:0.02778em;">r</span><span class="mord mathnormal">t</span><span class="mord mathnormal">e</span><span class="mord mathnormal">m</span><span class="mord mathnormal">p</span><span class="mord mathnormal" style="margin-right:0.02778em;">or</span><span class="mord mathnormal">a</span><span class="mord mathnormal" style="margin-right:0.03588em;">ry</span><span class="mord mathnormal">p</span><span class="mord mathnormal">a</span><span class="mord mathnormal">ss</span><span class="mord mathnormal" style="margin-right:0.02691em;">w</span><span class="mord mathnormal" style="margin-right:0.02778em;">or</span><span class="mord mathnormal">d</span><span class="mord mathnormal">i</span><span class="mord mathnormal">s</span></span></span></span>{event.request.codeParameter}`;
    event.response.smsMessage = message;
    event.response.emailMessage = message;
    event.response.emailSubject = "Welcome to the service";
  }
  return event;
};

export { handler };

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

Custom message Lambda trigger - Amazon Cognito (original) (raw)

Note

Topics

Custom message Lambda trigger sources

Custom message Lambda trigger parameters

Custom message request parameters

Custom message response parameters

Custom message for sign-up example

Custom message for admin create user example