"mobiletargeting:PutEvents"
],
"Resource": "arn:aws:mobiletargeting:region:accountId:apps/projectId/
endpoints/*"
}, {
"Effect": "Allow",
"Action": "mobiletargeting:PhoneNumberValidate",
"Resource": "arn:aws:mobiletargeting:region:accountId:phone/number/validate"
} ] }
In the preceding example, do the following:
• Replace region with the AWS Region that you use Amazon Pinpoint in, such as us-east-1 or eu-central-1.
TipFor a complete list of AWS Regions where Amazon Pinpoint is available, see AWS regions and endpoints in the AWS General Reference.
• Replace accountId with the unique ID for your AWS account.
• Replace projectId with the unique ID of the project that you created in Step 1.1 (p. 20) of this tutorial.
NoteThe logs actions enable Lambda to log its output in CloudWatch Logs.
4. Choose Review policy.
5. For Name, enter a name for the policy, such as RegistrationFormPolicy. Choose Create policy.
Step 2.2: Create an IAM role
To create the role
1. Open the IAM console at https://console.aws.amazon.com/iam/.
2. In the IAM console, in the navigation pane, choose Roles, and then choose Create role.
3. Under Choose the service that will use this role, choose Lambda, and then choose Next:
Permissions.
NoteThe service that you choose in this step isn't important—regardless of the service that you choose, you apply your own policy in the next step.
4. Under Attach permissions policies, choose the policy that you created in the previous section, and then choose Next: Tags.
5. Choose Next: Review.
6. Under Review, for Name, enter a name for the role, such as SMSRegistrationForm. Choose Create role.
Next: Create Lambda functions (p. 24)
Step 3: Create Lambda functions
This solution uses two Lambda functions. This section shows you how to create and configure these functions. Later, you set up API Gateway and Amazon Pinpoint to execute these functions when certain
Step 3: Create Lambda functions
events occur. Both of these functions create and update endpoints in the Amazon Pinpoint project that you specify. The first function also uses the phone number validation feature.
Step 3.1: Create the function that validates customer information and creates endpoints
The first function takes input from your registration form, which it receives from Amazon API Gateway.
It uses this information to obtain information about the customer's phone number by using the phone number validation (p. 116) feature of Amazon Pinpoint. The function then uses the validated data to create a new endpoint in the Amazon Pinpoint project that you specify. By default, the endpoint that the function creates is opted out of future communications from you, but this status can be changed by the second function. Finally, this function sends the customer a message asking them to verify that they want to receive SMS communications from you.
To create the Lambda function
1. Open the AWS Lambda console at https://console.aws.amazon.com/lambda/.
2. Choose Create function.
3. Under Create a function, choose Blueprints.
4. In the search field, enter hello, and then press Enter. In the list of results, choose the hello-world Node.js function, as shown in the following image. Choose Configure.
5. Under Basic information, do the following:
• For Name, enter a name for the function, such as RegistrationForm.
• For Role, select Choose an existing role.
Step 3: Create Lambda functions
• For Existing role, choose the SMSRegistrationForm role that you created in Step 2.2 (p. 24).
When you finish, choose Create function.
6. Delete the sample function in the code editor, and then paste the following code:
var AWS = require('aws-sdk');
var pinpoint = new AWS.Pinpoint({region: process.env.region});
// Make sure the SMS channel is enabled for the projectId that you specify.
// See: https://docs.aws.amazon.com/pinpoint/latest/userguide/channels-sms-setup.html var projectId = process.env.projectId;
// You need a dedicated long code in order to use two-way SMS.
// See: https://docs.aws.amazon.com/pinpoint/latest/userguide/channels-voice-manage.html#channels-voice-manage-request-phone-numbers
var originationNumber = process.env.originationNumber;
// This message is spread across multiple lines for improved readability.
var message = "ExampleCorp: Reply YES to confirm your subscription. 2 msgs per "
+ "month. No purchase req'd. Msg&data rates may apply. Terms: "
+ "example.com/terms-sms";
var messageType = "TRANSACTIONAL";
exports.handler = (event, context, callback) => { console.log('Received event:', event);
validateNumber(event);
};
function validateNumber (event) {
var destinationNumber = event.destinationNumber;
if (destinationNumber.length == 10) {
destinationNumber = "+1" + destinationNumber;
} var params = {
NumberValidateRequest: { IsoCountryCode: 'US',
PhoneNumber: destinationNumber }
};
pinpoint.phoneNumberValidate(params, function(err, data) { if (err) {
if (data['NumberValidateResponse']['PhoneTypeCode'] == 0) {
createEndpoint(data, event.firstName, event.lastName, event.source);
} else {
console.log("Received a phone number that isn't capable of receiving "
+"SMS messages. No endpoint created.");
} } });
}
function createEndpoint(data, firstName, lastName, source) {
var destinationNumber = data['NumberValidateResponse']['CleansedPhoneNumberE164'];
var endpointId = data['NumberValidateResponse']
['CleansedPhoneNumberE164'].substring(1);
var params = {
Step 3: Create Lambda functions
ApplicationId: projectId,
// The Endpoint ID is equal to the cleansed phone number minus the leading // plus sign. This makes it easier to easily update the endpoint later.
EndpointId: endpointId, EndpointRequest: { ChannelType: 'SMS',
Address: destinationNumber,
// OptOut is set to ALL (that is, endpoint is opted out of all messages) // because the recipient hasn't confirmed their subscription at this // point. When they confirm, a different Lambda function changes this // value to NONE (not opted out).
OptOut: 'ALL', Location: {
PostalCode:data['NumberValidateResponse']['ZipCode'], City:data['NumberValidateResponse']['City'],
Country:data['NumberValidateResponse']['CountryCodeIso2'], },
Demographic: {
Timezone:data['NumberValidateResponse']['Timezone']
},
}; pinpoint.updateEndpoint(params, function(err,data) { if (err) {
sendConfirmation(destinationNumber);
} });
}
function sendConfirmation(destinationNumber) { var params = {
ApplicationId: projectId, MessageRequest: {
Step 3: Create Lambda functions
};
pinpoint.sendMessages(params, function(err, data) { // If something goes wrong, print an error message.
if(err) {
console.log(err.message);
// Otherwise, show the unique ID for the message.
} else {
console.log("Message sent! "
+ data['MessageResponse']['Result'][destinationNumber]['StatusMessage']);
} });
}
7. Under Environment variables, do the following:
• In the first row, create a variable with a key of originationNumber. Next, set the value to the phone number of the dedicated long code that you received in Step 1.2 (p. 21).
NoteBe sure to include the plus sign (+) and the country code for the phone number. Don't include any other special characters, such as dashes (-), periods (.), or parentheses.
• In the second row, create a variable with a key of projectId. Next, set the value to the unique ID of the project that you created in Step 1.1 (p. 20).
• In the third row, create a variable with a key of region. Next, set the value to the Region that you use Amazon Pinpoint in, such as us-east-1 or us-west-2.
When you finish, the Environment Variables section should resemble the example shown in the following image.
8. At the top of the page, choose Save.
Step 3.1.1: Test the function
After you create the function, you should test it to make sure that it's configured properly. Also, make sure that the IAM role you created has the appropriate permissions.
To test the function 1. Choose Test.
2. On the Configure test event window, do the following:
• Choose Create new test event.
Step 3: Create Lambda functions
• For Event name, enter a name for the test event, such as MyPhoneNumber.
• Erase the example code in the code editor. Paste the following code:
{
"destinationNumber": "2065550142", "firstName": "Carlos",
"lastName": "Salazar",
"source": "Registration form test"
}
• In the preceding code example, replace the values of the destinationNumber, firstName, and lastName attributes with the values that you want to use for testing, such as your personal contact details. When you test this function, it sends an SMS message to the phone number that you specify in the destinationNumber attribute. Make sure that the phone number that you specify is able to receive SMS messages.
• Choose Create.
3. Choose Test again.
4. Under Execution result: succeeded, choose Details. In the Log output section, review the output of the function. Make sure that the function ran without errors.
Check the device that's associated with the destinationNumber that you specified to make sure that it received the test message.
5. Open the Amazon Pinpoint console at https://console.aws.amazon.com/pinpoint/.
6. On the All projects page, choose the project that you created in Step 1.1 (p. 20).
7. In the navigation pane, choose Segments. On the Segments page, choose Create a segment.
8. In Segment group 1, under Add filters to refine your segment, choose Filter by user.
9. For Choose a user attribute, choose FirstName. Then, for Choose values, choose the first name that you specified in the test event.
The Segment estimate section should show that there are zero eligible endpoints, and one total endpoint, as shown in the following image. This result is expected. When the function creates a new endpoint, the endpoint is opted out. Segments in Amazon Pinpoint automatically exclude opted-out endpoints.
Step 3: Create Lambda functions
Step 3.2: Create the function that opts in customers to your communications
The second function is only executed when a customer replies to the message that's sent by the first function. If the customer's reply includes the keyword that you specified in Step 1.3 (p. 21), the
function updates their endpoint record to opt them in to future communications. Amazon Pinpoint also automatically responds with the message that you specified in Step 1.3.
If the customer doesn't respond, or responds with anything other than the designated keyword, then nothing happens. The customer's endpoint remains in Amazon Pinpoint, but it can't be targeted by segments.
To create the Lambda function
1. Open the AWS Lambda console at https://console.aws.amazon.com/lambda/.
2. Choose Create function.
3. Under Create function, choose Blueprints.
4. In the search field, enter hello, and then press Enter. In the list of results, choose the hello-world Node.js function, as shown in the following image. Choose Configure.
5. Under Basic information, do the following:
• For Name, enter a name for the function, such as RegistrationForm_OptIn.
• For Role, select Choose an existing role.
• For Existing role, choose the SMSRegistrationForm role that you created in Step 2.2 (p. 24).
When you finish, choose Create function.
6. Delete the sample function in the code editor, and then paste the following code:
var AWS = require('aws-sdk');
var projectId = process.env.projectId;
var confirmKeyword = process.env.confirmKeyword.toLowerCase();
var pinpoint = new AWS.Pinpoint({region: process.env.region});
exports.handler = (event, context) => { console.log('Received event:', event);
var timestamp = event.Records[0].Sns.Timestamp;
var message = JSON.parse(event.Records[0].Sns.Message);
var originationNumber = message.originationNumber;
var response = message.messageBody.toLowerCase();
if (response.includes(confirmKeyword)) {
updateEndpointOptIn(originationNumber, timestamp);
}};
function updateEndpointOptIn (originationNumber, timestamp) { var endpointId = originationNumber.substring(1);
var params = {
ApplicationId: projectId, EndpointId: endpointId, EndpointRequest: {
Address: originationNumber, ChannelType: 'SMS',
OptOut: 'NONE', Attributes: { OptInTimestamp: [
Step 3: Create Lambda functions
timestamp ]
}, }
}; pinpoint.updateEndpoint(params, function(err, data) { if (err) {
console.log("An error occurred.\n");
console.log(err, err.stack);
} else {
console.log("Successfully changed the opt status of endpoint ID " + endpointId);
} });
}
7. Under Environment variables, do the following:
• In the first row, create a variable with a key of projectId. Next, set the value to the unique ID of the project that you created in Step 1.1 (p. 20).
• In the second row, create a variable with a key of region. Next, set the value to the Region that you use Amazon Pinpoint in, such as us-east-1 or us-west-2.
• In the third row, create a variable with a key of confirmKeyword. Next, set the value to the confirmation keyword that you created in Step 1.3 (p. 21).
NoteThe keyword isn't case sensitive. This function converts the incoming message to lowercase letters.
When you finish, the Environment Variables section should resemble the example shown in the following image.
8. At the top of the page, choose Save.
Step 3.2.1: Test the function
After you create the function, you should test it to make sure that it's configured properly. Also, make sure that the IAM role you created has the appropriate permissions.
To test the function 1. Choose Test.
2. On the Configure test event window, do the following: