Behind the Scenes with Twilio Automated Notifications

We are always on the lookout for solutions that elegantly address business needs in a Salesforce implementation. We recently built out a nifty Twilio integration for outgoing text messages for one of our clients. Here is our CRM Developer Mike Smith’s take on the project.

The Challenge

A large training-centric organization required automated dynamically generated outbound text and voice calls to their students and instructors to remind them of upcoming classes, assignments, upcoming training requirement deadlines, and other related communications. In addition, the students and instructors are not all English speakers, and as such both the audio and text notifications had to support multiple languages based on the recipients’ “Communication Language” field value.

The Solution

Twilio was selected as the service to use for the outbound notifications primarily due to their strong integration with Salesforce.com and their robust API (Application Programming Interface). The first step to meet the client’s primary needs was to build out a template data model that would offer the client’s own system administrators the ability to maintain the content directly without requiring apex knowledge.

Solution Architecture

Four custom objects were utilized to build out the template structure:

• Notification Template : Parent object with one record per template (ex: Class Reminder)

• Notification Template Type: Child of “Notification Template” with one record per type of template (Phone, SMS) and Language (English, Spanish, Russian, etc.).

An example of the “Notification Template Types” is below. Text messages are configured with one template type record per language, whereas the Phone template is only a single template type record because the audio WAV files will be dynamically selected based on the recipient’s language.

To cover all of the possible languages and options for outbound phone notifications, it was necessary to build a library of 900+ WAV files within Salesforce.com. A critical requirement in this model is that each WAV file must be externally available to enable Twilio to play back the WAV file in the call. Similar to the Notification Template model, Pre-Record Audio files are structured with a single record for the template name (ex: ”STUDENT_CLASS_REMINDER_A”) with multiple child records attached - one per language.

Example of a pre-recorded audio template in Salesforce.com:

Generating a Notification

Still following the objective of allowing the client to maintain notifications long-term, we decided to utilize Salesforce.com’s standard Workflow Rule functionality, including time-dependent rules,  to generate and/or queue notifications. Salesforce.com limits what a Workflow Rule can actually do to one of four actions: update a field, send an email, create a task, or call an external webservice. Making this work for our client required the use of an “Inbound Apex Email Handler”. Each of the workflow rules that generated a notification were configured to send an email to a special custom Salesforce.com email address with a specially formatted body that contains information about the notification to queue:

Notification":

{ "MessageName": "STUDENT_CLASS_REMINDER",

"ContactID": "003d000001YIUCN",

"ClassID": "a0cd0000003fDlN",

"DeliveryMethod" : "",

"rosterStatus": "Enrolled"

}

}

The custom developed “Inbound Apex Email Handler” processes the above message body to retrieve the template (STUDENT_CLASS_REMINDER) and merge it with the Recipient (Contact) and related Class as specified by the ID’s. Based on the Recipient’s Notification Preference (Phone or Text Message) and their selected Communication Language, the handler creates a new record in the NotificationQueue object with the properly formatted message to be sent. I should note that this example is greatly simplified, though. The handler is capable of processing various types of notifications and options, such as sending a notice to all registered students within a single class.

Outbound phone call templates are built differently than text messages. If the template specifies a merge field such as “{Audio.STUDENT_CLASS_REMINDER_A}”, the final call to Twilio will convert that into the required code (called TwiML) using the WAV file in the Communication language of the Student. Our client does not need to worry about building out all the possible audio template possibilities. The notifications engine encapsulates all of that logic in the custom code. They simply need to ensure that there are WAV files for all of the supported languages. New languages can be added at any time by simply updating the Language picklist fields and attaching a new WAV file in that language.

Sending the Notifications

Once the notifications are added to the Notifications Queue object, a custom scheduled apex batch runs every 10 minutes to send out the notifications based on the delivery method, language, etc.

To avoid bombarding their students and instructors with dozens of text messages or phone calls in a short period of time, or after hours, the Notifications Engine respects a client-defined quiet time period and also limits the number of outbound calls or texts sent to a single phone number.

Summary and Lessons Learned

The business need, though at first glance appears to be relatively straight forward, was obviously more complex to scope and build. Through the initial project discussions we flushed out the detailed requirements and quickly identified that client ownership and and flexibility of the templates and notification types were critical components. The client already had a large library of WAV files with audio content from their existing system, though that system had been hard-coded to use specific audio files rather than something more generic that the client could easily maintain. In addition, their legacy system offered no ability to create new notification types or change how or when notifications were delivered.

We and the client identified a few key lessons learned that others should be aware of when implementing a solution such as this:

• Don’t over-notify your users. The client’s initial project requirements stated that students and instructors were to be notified by phone or text on many different actions. This very quickly proved to be overwhelming for their users. Luckily, the solution architecture made it easy for them to quickly disable unneeded notifications.

• Your data is never as good as you think it is. Sending text messages or making phone calls obviously requires a valid phone number and needs to support opt-out and handle exceptions such as a bad phone number. Not surprisingly, the quality of the phone numbers imported from the client’s legacy database was somewhat questionable. Many phone numbers were missing and some were not even phone numbers or had extensions. To help fix the bad data, their students and instructors are required to review their profile every 30 days upon logging into their Training Portal.

• Be wary of Salesforce.com governor limits. Salesforce.com tracks how many outbound callouts are made (i.e., calling the Twilio services to send the text message or make a phone call) as well as the number of outbound email messages that can be sent through workflow rules per day. Always liberally estimate the expected volume during your project scoping phase and open a support case with Salesforce.com to request an increase in these values if you feel they will exceed their limits. 

Ready to chat about how Idealist Consulting can help you connect solutions like Twilio with Salesforce?

LET'S TALK