Engaging Salesforce Customers with Bidirectional SMS Using AWS

By Kishore Dhamodaran, Sr. Solutions Architect – AWS
By Jared Wiener, Solutions Architect – AWS

Communication with end users is an important part of managing a customer relationship. For organizations leveraging both Salesforce and Amazon Web Services (AWS), the new Salesforce Event Relay using Amazon EventBridge enables developers to trigger AWS actions like sending an SMS message using Amazon Simple Notification Service (SNS) in response to an event within Salesforce.

Salesforce is an AWS Partner and customer relationship management (CRM) platform, giving organizations a single, shared view of activity across their marketing, sales, commerce, and service departments. Salesforce functionality can be extended to take advantage of the infrastructure and managed services offered by AWS.

Salesforce Event Relays enable bidirectional event flows between Salesforce and AWS through Amazon EventBridge. This opens up opportunities to build event-driven, near real-time applications, responding to feedback and outside triggers as they happen.

From sending appointment reminders to customers, to providing the latest update on a support case, this pattern creates new opportunities to engage with customers in their preferred mode of communication. Developers building off of this integration can focus on the user experience, without the overhead of having to manage connectivity across platforms.

In this post, we will use the bidirectional integration to pass events from Salesforce to AWS to send SMS messages, and notify you when a user responds to your message.

Solution Overview

This is an event-driven architecture, leveraging Custom Platform Events in Salesforce. Using Event Relay as an interface to Amazon EventBridge, the event is passed to an AWS Step Functions state machine, which triggers Amazon SNS to send the SMS message.

When the user responds to the SMS message, Amazon Pinpoint forwards it to an AWS Lambda function through an SNS topic. The Lambda function triggers an EventBridge event rule that uses an API destination endpoint to relay the message to a Salesforce inbound Platform Event.

Figure 1 – Solution overview.

Prerequisites

• Salesforce account with Event Relays enabled.
• Postman, REST API Tool, and the Salesforce Postman API Collection.
• AWS account with a role that has sufficient access to provision the required infrastructure.
• Credentials that enable you to interact with your AWS account.
• 10DLC to send SMS messages.

Set Up Salesforce Event Relay Configuration and Connected App

Use this guide as a reference if you need additional help configuring Event Relay or need information necessary to set up your API client.

1. Create a Platform Event in Salesforce; this will be the event that will be sent to AWS.
   • From Salesforce Setup, navigate to Platform Events and choose New Platform Event.

Figure 2 – Salesforce New Platform Event form.

• • Enter a label and plural label, and choose Save; we will call this “GenericSMS.”

Figure 3 – Salesforce New Custom Field form.

• • Under Custom Fields & Relationships, select New for each required field, and configure based on the expected payload from EventBridge.

Figure 4 – Salesforce New Custom Field form.

• • We will create two fields, Message and PhoneNumber. Be sure your PhoneNumber field length allows for your full internationally formatted phone number; for example, in the U.S. it would be +12125551212, so a length of 12.

Figure 5 – Salesforce Platform Event after creation.

2. In Postman, log in to your Salesforce account following the directions in the Postman Collection. To create a channel for a custom Platform Event, send a POST request to {{_endpoint}}/services/data/v{{version}}/sobjects/PlatformEventChannel with a JSON body:

{
    "FullName": "SMSChannel__chn",
    "Metadata": {
        "channelType": "event",
        "label": "Custom Channel for Relaying SMS Platform Events"
    }
}

3.	You should receive a response similar to the following—save the id field value.
{
  "id" : "0YL9A000000000kWAA", 
    "success" : true,
    "errors" : [ ],
    "warnings" : [ ],
    "infos" : [ ]
}

3. To create a Channel Member to associate the custom platform event, send a POST request to https://<SFDomain>/services/data/v54.0/tooling/sobjects/PlatformEventChannelMember with JSON body:

{
    "FullName": "SMSChannel_chn_GenericSMS_e",
    "Metadata": {
        "eventChannel": "SMSChannel__chn",
        "selectedEntity": "GenericSMS__e"
    }
}

4. You should receive a response similar to this—once again, save the id field value:

   {
    "id" : "0v89A000000083KQAQ",    
    "success" : true,
    "errors" : [ ],
    "warnings" : [ ],
    "infos" : [ ]
   }

5. Create a Named Credential by sending a POST request to https://<SFDomain>/services/data/v54.0/tooling/sobjects/NamedCredential/ with the following JSON body. Replace <aws_region> and <aws_account_number> and match the AWS account which will host EventBridge. (AWS Region must be ALL CAPS.)

{
 "FullName" : "MyRelayNamedCredential",
 "Metadata" : {
 "endpoint" : "arn:aws:<aws_region>:<aws_account_number>",
 "generateAuthorizationHeader" : true,
 "label" : "MyRelayNamedCredential",
 "principalType" : "NamedUser",
 "protocol" : "NoAuthentication"
 }
}

6. Create an Event Relay Configuration by sending a POST request to https://<SFDomain>/services/data/v54.0/tooling/sobjects/EventRelayConfig/with the following JSON body. The Event Channel is the ID returned from Step 3, and the MyRelayNamedCredential referenced in the DestinationResourceName is the credential from Step 6.

{
  "DeveloperName": "MyEventRelay",
  "MasterLabel" : "MyEventRelay",
  "EventChannel" : "0YLXXXXXXXXXXXXXXX",
  "DestinationResourceName" : "callout:MyRelayNamedCredential"
}

7. You will receive a response similar to the following:

{
  "id" : "7k2RM000000000VYAQ",
  "success" : true,
  "errors" : [ ],
  "warnings" : [ ],
  "infos" : [ ]
}

8. In the AWS Management Console, under EventBridge > Partner event sources, choose the pending source and associate it with an event bus.

Figure 6 – An example of a pending partner event source.

9. You can now create rules on the bus to send to a state machine. Create a new Step Functions state machine; sample code below:

{
  "Comment": "A state machine to send SMS",
  "StartAt": "SNS Publish",
  "States": {
    "SNS Publish": {
      "Type": "Task",
      "Resource": "arn:aws:states:::aws-sdk:sns:publish",
      "Parameters": {
        "Message.$": "$.Message__c",
        "PhoneNumber.$": "$.PhoneNumber__c"
      },
      "InputPath": "$.detail.payload",
      "End": true
    }
  }
}

10. By default, the Event Relay will be created in a stopped state. To start sending events to AWS, send a PATCH request to https://<SFDomain>/services/data/v54.0/tooling/sobjects/EventRelayConfig/[EventRelayConfigId], using the Event Relay Configuration ID from Step 8, and a JSON body:

{
  "State": "RUN"
}

11. A successful response will return HTTP status 204 / No Content.
    .
12. Create a Platform Event to receive inbound messages:
    • From Salesforce Setup, go to Platform Events and choose New Platform Event.
    • Enter a label and plural label, and choose Save.
    • Under Custom Fields & Relationships, select New for each required field, and configure based on the expected payload from EventBridge.
      .
13. Create a Connected App using the instructions from “Create a Connected App in Salesforce for OAuth” section in the Event Bus Relay guide.
    .
14. To verify the events sent to Salesforce are being received, set up a custom flow to email with the Platform Event from Step 1 as a trigger:
    • From Salesforce Setup, go to Process Automation > Flows, and choose New Flow.
    • Choose Platform Event—Triggered Flow and then select Create.
    • On the Start object, choose + Choose Platform Event and search for your newly-created event from Step 1. Select it from the dropdown, and choose Done.
    • Choose the “+” button between Start and End. Add a new Action.
    • On the left sidebar, select Email, and on the right side select Send Email from the Actions field.
    • After selecting a Label and an API Name, set a Body and Subject. You can use variables from the incoming event in both; for example, {!$Record.Message__c} is the Message__c field from the triggering event.
    • Toggle Recipient Email Addresses (comma-separated) to on, and then enter your email address.
    • Choose Done, and then Save.
    • Choose Activate on the top right.
    • When you send a new event, you should receive an email, though it may take about a minute or so.

Set Up AWS Resources

1. Clone the GitHub repository to your local machine:git clone https://github.com/aws-samples/amazon-eventbridge-salesforce-sms.git

2. Deploy the resources using AWS Serverless Application Model (AWS SAM). The deploy command processes the AWS SAM template file to create the necessary resources in AWS. Choose Salesforce-AWS-SMS-Stack as the stack name and the AWS region you want to deploy your solution to.

cd amazon-eventbridge-salesforce-sms
sam build
sam deploy --guided --capabilities CAPABILITY_IAM CAPABILITY_NAMED_IAM

Use the default parameters or replace with different values if necessary. For example, to get counts of a different filler phrase, replace the FillerPhrase parameter.

Once AWS SAM successfully deploys the resources, associate your phone number with the SNS topic just created by the SAM deployment (SMSResponseSNSTopic), which you can do using the Pinpoint SDK:

• Set the TwoWayEnabled property to true.
• Set the TwoWayChannelArn property to the Amazon Resource Name (ARN) of the just created SNS topic.
• For Lambda reference, see AWS JavaScript SDK documentation of the PhoneNumberInformation object.

Alternatively, enable the two-way SMS via the console:

• Navigate to the Amazon Pinpoint console. Under SMS and Voice, choose the phone number followed by Two-way SMS. Then, choose the option to Enable two-way SMS.
• For Incoming messages destination, choose an existing SNS topic, and choose the SNS topic created by AWS CloudFormation.
• Finally, choose Save.

Sending and Receiving Messages

• Use Postman API to send a test SMS message to your mobile phone.
• Send a response from your mobile phone.
• Verify you received an email with the response.

Conclusion

In this post, we showed how you can use the new Salesforce Event Relay and Amazon EventBridge to create event-driven applications to engage with your customers.

You can extend this to build business logic and flows within Salesforce platform to build an automated, conversational SMS application.