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
SMS features are managed in the SysAdmin area by Heuristic Solutions. For more information, see SMS Notification Configuration
Enabling SMS for a Notification
Once the feature toggle is enabled in the SysAdmin area, you can “SMS-enable” a Notification in the Admin → Automations → Templates area.
When a SNSSMS-enabled 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.
Enabling a phone number for SMS notifications
Once the feature toggle is enabled in the SysAdmin area, individual phone numbers can “opt-in” to notifications from the My Account and Account Profile screens.
Technically speaking, the opt-in actually happens when a user sends the word “START” to the number used for sending notifications. However, through the UI the user can request an “invitation” message which they can then reply to, simplifying the process.
The opt-in process satisfies all regulatory compliance requirements by identifying the purpose of the notifications, the expected frequency, the fact that data rates may apply, and how to opt-out in the future.
Configuring the “opt-in” messaging
There are two Content Blocks that can be customized to control the messaging.
Content Block | Purpose |
|---|---|
MyAccount → SMS Opt-in Confirmation Prompt | Displayed in the modal popup during the opt-in process. Can be customized to provide a more informative explanation of how SMS messaging will be used. |
MyAccount → SMS Opt-in Confirmation Text | This is the body of the “welcome” SMS message that is sent to a user immediately after they opt-in. |
Using “Test Mode” and “Override Number” settings
There are several settings in App Config that are relevant to the functioning of SMS.
App Setting
Usage
EnableSmsOverrideNumber
Valid values: true/false
Forces all SMS messages to be sent to a single number, regardless of what user it was intended for. Configure the number itself in SmsOverrideNumber
EnableSmsTestMode
This will force the gateway to use the alternative settings defined in TestSmsGatewayAuthentication and TestSmsGatewaySettings rather than the settings in SmsGatewayAuthentication and SmsGatewaySettings.
The purpose of the test mode is so you can easily swap out settings. There is nothing special about test mode settings in terms of how our system interprets them, it is merely an alternate set of credentials and settings.
Twilio Test Mode
All Twilio accounts have both “live” credentials and “test” credentials. The test credentials will not allow you to send real messages but will instead be validated as described in this article: https://www.twilio.com/docs/iam/test-credentials. The purpose of the test credentials is to simulate success and error conditions without actually sending SMS messages and incurring cost.
The intended use of these features is to allow us to use the test credentials by entering them in the TestSmsGatewayAuthentication setting, entering a “FROM” magic number (documented in the above link) in the TestSmsGatewaySettings and enabling test mode.
You may also enable the override number and enter a “TO” magic number into the override number field to simulate errors involving the “TO” number. |
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