Custom message Lambda trigger
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 the
codeParameter string into the message body where you want the verification
code to appear. When Amazon Cognito receives this response, Amazon Cognito replaces the
codeParameter string with the actual verification code.
The input event for a custom message Lambda function with the
CustomMessage_AdminCreateUser trigger source includes a username and
verification code. Because an admin-created user must receive both their username and
code, the response from your function must include placeholder variables for the
username and code. The placeholders for your message are the values of
request.usernameParameter and request.codeParameter. These
values are typically {username} and {####}; as a best
practice, reference the input values instead of hardcoding the variable names.
Messages that you configure in the Message templates menu of the Amazon Cognito console can override a body that your custom message function sets. If your function's message doesn't appear, check whether a console message template is configured for the same event. For more information, see Configuring MFA, authentication, verification and invitation messages.
Topics
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 the common parameters that Amazon Cognito adds to all requests.
Custom message request parameters
- userAttributes
-
One or more name-value pairs representing user attributes.
- codeParameter
-
A string for you to use as the placeholder for the verification code in the custom message.
- usernameParameter
-
The username. Amazon Cognito includes this parameter in requests that result from admin-created users.
- clientMetadata
-
One or more key-value pairs that you can provide as custom input to the Lambda function that you specify for the custom message trigger. The request that invokes a custom message function doesn't include data passed in the ClientMetadata parameter in AdminInitiateAuth and InitiateAuth API operations. To pass this data to your Lambda function, you can use the ClientMetadata parameter in the following API actions:
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.
To send custom email messages and subject lines from this trigger, configure
your user pool to send email with Amazon Simple Email Service. With this configuration, the
EmailSendingAccount attribute of your user pool is
DEVELOPER. For more information, see Amazon SES email configuration.
- smsMessage
-
The custom SMS message to be sent to your users. Must include the
codeParametervalue that you received in the request. - emailMessage
-
The custom email message to send to your users. You can use HTML formatting in the
emailMessageparameter. Must include thecodeParametervalue that you received in the request as the variable{####}. Use this parameter when theEmailSendingAccountattribute of your user pool isDEVELOPER. - emailSubject
-
The subject line for the custom message. Use this parameter when the
EmailSendingAccountattribute of your user pool isDEVELOPER.
Custom message for sign-up example
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.
If your function returns an email message longer than 20,000 UTF-8 characters, Amazon Cognito doesn't return an error. Instead, it silently discards your custom message and sends the default message for that event. If your custom message isn't reaching users, check its length against this limit first.
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:
Custom message for admin create user example
The request that Amazon Cognito sent to this example custom message Lambda function has a
triggerSource 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 and
usernameParameter into smsMessage and
emailMessage 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.
If your function returns an email message longer than 20,000 UTF-8 characters, Amazon Cognito doesn't return an error. Instead, it silently discards your custom message and sends the default message for that event. If your custom message isn't reaching users, check its length against this limit first.
The response includes messages for both SMS and email.
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: