SMS notifications were introduced in 10.2.0. Notifications are always sent via email, but can be optionally configured to be sent as a text message as well.
SMS recipients receive a short text message containing the notification’s subject line, plus a link to view the full notification within the LearningBuilder Communications History page.
Capabilities and Use Cases
The following user stories are supported:
System users accustomed to SMS messaging can choose to receive their system notifications via text, rather than email
Persons with multiple accounts in the system, such as a Practitioner and a Provider account, can use the same phone number for both accounts but only receive notifications for one account via SMS
Administrators can see delivery status information, so that they can tell whether a given message was sent via SMS and if it was successfully queued for delivery
Recipients of a text message can opt-out from further messages directly via SMS reply containing the word “STOP”, without needing to log into the system.
During testing, SMS messaging can be suppressed or funneled to a specific phone number so that “real” texts are not sent out.
Configuration
All phone numbers in the config settings should be specified in E164 format.
E164 format for the US phone number “(123) 456-7890” would be “+11234567890”
Create a Twilio account
Go to http://www.twilio.com and create an account, and purchase a phone number.
LearningBuilder supports “normal” ten-digit numbers (called long codes), Toll-Free SMS numbers, and 5-digit “short codes” designed specifically for application-to-person SMS usage.
Each phone number type has a different cost structure and maximum throughput.
Configure the SMS Gateway in AppConfig
Obtain the AccountSid and AuthToken from the Twilio site, and then configure the following AppConfig settings:
Setting | Value |
|---|---|
| Twilio |
|
|
|
|
Send a test SMS message
Before fully enabling SMS features in LearningBuilder, send a test message by going to /SysAdmin/SmsNotificationsTestHarness and sending a test message. This allows you to verify that the configuration is correct.
Enable SMS features
When satisfied with the configuration, set the EnableSmsNotifications setting to “true” to enable the feature flag. This will allow you to identify which Notifications should be SMS-enabled.
Enable SMS for a Notification
Once the feature toggle is enabled, you can “SMS-enable” a Notification in the Admin → Automations → Templates area.
Once SMS enabled, when a Notification is sent to a recipient that has a SMS-enabled phone number, that recipient will receive a text message containing the subject line and a link to view the full message in the Communications History of the My Account area.
SMS Override Number
If you are testing and do not want to send test messages to real users, but you do want to generate real messages for testing purposes, then enable SMS Overrides. When this feature is enabled, all outgoing SMS messages will be re-routed to a specific phone number.
Setting | Value |
|---|---|
| true |
| The desired number, in E164 format |
Disabling SMS messages during testing
If you are testing and do not want to generate any text messages, then enable SMS Test Mode. This does a few things:
It suppresses real SMS messages from being sent
It allows you to use Twilio Magic Numbers in the “from” and “to” phone numbers to simulate various events, such as a failed delivery or a blocked number
Setting | Value |
|---|---|
| true |
|
|
|
|
Limitations
Notifications are always sent via email, and can optionally also be sent via SMS. Notifications cannot be sent only via SMS.
The SMS message contains the subject of the email message and a link to view the notification within LearningBuilder. The notification body is not delivered via SMS.
The SMS delivery network may throttle outgoing messages to as few as 1-3 messages per second; if a scheduled Notification generates a large number of SMS messages, there may be a delay between the delivery of the email version and the delivery of the SMS version.
Business Rules
For detailed business rules and flowcharts, see /wiki/spaces/DOCS/pages/900890883