Custom Message Lambda Trigger
Amazon Cognito invokes this trigger before sending an email or phone verification
message or a
multi-factor authentication (MFA) code, allowing you to customize the message dynamically.
Static custom messages can be edited in the Message Customizations tab
of the Amazon Cognito console
The request includes codeParameter
, which is a string that acts as a
placeholder for the code that's being delivered to the user. Insert the
codeParameter
string into the message body, at the position where you want
the verification code to be inserted. On receiving this response, the Amazon Cognito
service replaces
the codeParameter
string with the actual verification code.
A custom message Lambda function with the CustomMessage_AdminCreateUser
trigger returns a user name and verification code and so the request must include
both
request.usernameParameter
and request.codeParameter
.
Topics
Custom Message Lambda Trigger Sources
triggerSource value | Triggering 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
These are the parameters required by this Lambda function in addition to the common parameters.
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 parameter. It is a required request parameter for the admin create user flow.
- 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. You can pass this data to your Lambda function by using the ClientMetadata parameter in the following API actions:
Custom Message Response Parameters
In the response, you specify the custom text to use in messages to your users.
- smsMessage
-
The custom SMS message to be sent to your users. Must include the
codeParameter
value received in the request. - emailMessage
-
The custom email message to be sent to your users. Must include the
codeParameter
value received in the request. If EmailSendingAccount is not DEVELOPER and EmailMessage is returned, 400 error codecom.amazonaws.cognito.identity.idp.model.InvalidLambdaResponseException
will be thrown. emailMessage is allowed only if UserPool's EmailSendingAccount is DEVELOPER. - emailSubject
-
The subject line for the custom message. If EmailSendingAccount is not DEVELOPER and EmailMessage is returned, 400 error code
com.amazonaws.cognito.identity.idp.model.InvalidLambdaResponseException
will be thrown. emailSubject is allowed only if UserPool's EmailSendingAccount is DEVELOPER.
Custom Message for Sign Up Example
This Lambda function is invoked to customize an email or SMS message when the service requires an app to send a verification code to the user.
A Lambda trigger can be invoked at multiple points: post-registration, resending
a
verification code, forgotten password, or verifying a user attribute. The response
includes messages for both SMS and email. The message must include the code parameter,
"####"
, which is the placeholder for the verification code that is
delivered to the user.
For email, the maximum length for the message is 20,000 UTF-8 characters, including the verification code. HTML tags can be used in these emails.
For SMS, the maximum length is 140 UTF-8 characters, including the verification code.
Amazon Cognito passes event information to your Lambda function. The function then returns the same event object back to Amazon Cognito, with any changes in the response. In the Lambda console, you can set up a test event with data that’s relevant to your Lambda trigger. The following is a test event for this code sample:
Custom Message for Admin Create User Example
A custom message Lambda function with the CustomMessage_AdminCreateUser
trigger returns a user name and verification code and so include both
request.usernameParameter
and request.codeParameter
in the
message body.
The code parameter value "####"
is a placeholder for the temporary
password and "username" is a placeholder for the username delivered to your user.
For email, the maximum length for the message is 20,000 UTF-8 characters, including the verification code. HTML tags can be used in these emails. For SMS, the maximum length is 140 UTF-8 characters, including the verification code.
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 back to Amazon Cognito, with any changes in the response. In the Lambda console, you can set up a test event with data that’s relevant to your Lambda trigger. The following is a test event for this code sample: