SMS - Administrator Setup

Configuration guide for administrators when setting up texting / SMS tools.

LegalServer Setup

There are several required, and some optional, steps site administrators must take to enable and setup this module. In summary, once you purchase the SMS add-on, you will then sign up with Twilio, then enter Twilio credentials into LegalServer's settings. LegalServer uses Twilio to send and receive messages.

Enable the SMS Tab

On the Admin > Users Roles (Permissions) page, edit the Administrator role and check the SMS box in the Viewable Navigation tabs section. Users do not need access to this tab to use the feature on cases. The SMS tab is useful for administrator testing and troubleshooting.

Optionally re-arrange the navigation tab order on the Admin > Top Level Navigation Bar/Search page, under the "Tabs" tab.

LegalServer Administrator Form

Enter your site's Twilio information on the Admin > Telephony & SMS page, and optionally enable SMS for reminders on calendar events, tasks, and deadlines.

The Twilio phone number you use for the demo site and live site must be two different Twilio numbers.

Note: The Master Consent Search list limits the consent search to just clients instead of all contacts within the system.

Enter the SID, Token, and Phone Number at Admin > Telephony and SMS. Repeat this process for your live site with a different Twilio phone number when you are done testing SMS on the demo site.

Note: Autoresponder settings are not shown, but will also appear in Admin > Telephony and SMS if that module is enabled.

Viewing SMS Message Logs for the Site

The SMS navigation tab page contains lists for all Scheduled, Sent, and Received SMS Messages.

Scheduled & Queue, Sent and Received tabs have filter options, which allow you to see messages by date range.

The Contact Consent tab (not shown above) will only appear if the option to use a master consent search list is selected on the Admin page. This allows searching across all consents in the database and editing individual records.

Note: The Master Consent Search list is not fully implemented. Do not check this box without contacting LegalServer Support.

Adding the SMS Block to a Form

Administrators must add the SMS Block to an auxiliary or branch logic form in the Case/Matter module on the Admin > Processes, Forms, and Profiles page.

Create a new auxiliary form named something like "Send SMS Text"; this form will have the SMS block on it, or a Branch Logic block (see "Requiring Client Consent to Receive Texts" below), and optionally one or more Instructions elements with organization policy about texting clients.
Create a new auxiliary process to call that the form, named something like "Send SMS Text to Client"
Add the new process to the Actions menu on the case profile

Not shown in the above screenshot is the "Omit Phone Number UI Formatting Requirements" configuration option. Check that box to allow entry of non-US (International) numbers. Whatever is entered in the phone number field will be sent to the SMS provider.

The SMS block should not be placed on profile pages. The block presents a 'live' set of fields and action buttons, and must be on an auxiliary process.

Adding List Views on Cases

The SMS Sent Log and SMS Received Log list view elements are available for case profiles.

Requiring Client Consent to Receive Texts

Site administrators can require users to indicate that a client has consented to receiving texts. Recording consent, and how to record it, are up to each site.

The SMS Consent Preferences block is available. The block ties consent to a specific phone number. If used, this block is typically placed on a separate auxiliary form, and the auxiliary process to send a text is two steps: the consent form, followed by the form with the SMS block on it.

For more flexibility, many sites create a custom field for "SMS Consent", either a boolean Yes/No field, or a lookup field that uses a custom lookup list with desired values. They will use that field in a branch logic block on the auxiliary form to display, or not, a branch logic from with the SMS block on it.

Site administrators can also make consent and sending two separate processes if desired; for example "Send SMS Text" and "SMS Client Consent". The consent form has the custom "SMS Consent" field on it, and other optional elements; for example, the client's mobile number, an instruction element with organization policy, the Add Case Note block to record who submitted the form and when, etc.

Optional: Add an SMS Alert on the LegalServer Home Page

Administrators can configure the Homepage Alert block to include alerts about SMS messages received on the logged in user's cases (includes pending, open, and closed cases).

Add the Homepage Alerts block and check "Show SMS Received Alerts Tab When Applicable". By default, only the Primary Assignment user on a case will get an alert on their home page. Site Administrators can change the "Show SMS Alerts for Assignment Types" setting on the Admin > Telephony & SMS page to "All Assignments" if desired.

If the home page on your site isn't dynamic (you don't see an Admin menu > Edit Profile link), you need to create a dynamic Home profile to use this block.

Preventing Messages from Being Sent to a Number

Stopping messages from being sent to a specific number is handled by the SMS provider. Twilio, for example, provides:

STOP, STOPALL, UNSUBSCRIBE, CANCEL, END, and QUIT - will stop customers from receiving messages from that particular Twilio number. When attempting to send a message to a subscriber that previously texted in any of the keywords mentioned above, Twilio's API will throw a 400 response with error code 21610.

Site administrators can also make the Send SMS auxiliary process two steps, and require the user to view/edit consent in the SMS Consent Preferences block before proceeding to the next form. Because we don't know if the user intends to send an SMS to the client or to a third party, such as a service provider, the SMS send tool will still appear on the form.

Twilio Setup - Required to Use SMS Tools!

Create a Twilio Account and Configure It

Twilio is a separate company and product. Visit https://www.twilio.org/ to create an account.

1) set up a trial account at twilio.com.

2) upgrade your trial account to a functional account.

A Trial account will not permit you to properly test SMS sending. Upgrade to a functional account before testing.

3) let your financial department know this account should auto-recharge or never run out of funds.

To avoid SMS messages not being sent or delivered and error messages for your users, your Twilio account should not be allowed to run out of funds. Accounts should be maintained with sufficient funds, or set to auto recharge.

4) log into your new account and create two phone numbers, one for your demo and one for your live site.

Getting two numbers from Twilio, one for your demo site and one for your live site, is not required, but is highly recommended. Do not use the same phone number on both your demo and live sites.

There is no need for phone numbers that have Fax features enabled. For security purposes, we highly recommend only enabling the features you intend to use. Additionally, you can set Geographic Permissions to limit what countries you can send SMS messages to as a way to limit potential exposure.

5) After creating an account, login at https://www.twilio.com to login and administer your account.

Make a note of your Twilio credentials and API key.

6) Optional: apply for a NonProfit Discount at Twilio

Apply for a kickstart credit and discounted pricing at Twilio.org.

Where are the Webhooks in Twilio?

Twilio sometimes moves things around, so take these instructions with a grant of salt.

Click on the "three dot menu" in the side bar on the main, and most, pages in Twilio.
Select "Phone Numbers" in that menu.
In your list of numbers, click on the one you want to configure, then scroll down to the "Messaging" section.

Enter the LegalServer Webhook in Twilio's Configuration for the Demo Site

The Webhook you will configure is what Twilio uses to send incoming messages to your site, and LegalServer uses to process those messages and create case notes (assuming the incoming number exists on a case) and alerts.

You must configure the webhook after 'A MESSAGE COMES IN' in the Twilio administration console at twilio.com.

The webhook URL you should enter is: https://your_site_abbreviation_goes_here-demo.legalserver.org/modules/sms/processor.php

Test the SMS tool on your Demo site

Create the processes need and familiarize yourself with how SMS works on the demo site.

Enter the LegalServer Webhook in Twilio's Configuration for the Live Site

You must configure the webhook after 'A MESSAGE COMES IN' in the Twilio administration console at twilio.com. The webhooks for your demo and live sites are different.

The webhook for your live site is : https://your_site_abbreviation_goes_here.legalserver.org/modules/sms/processor.php

Set the Voice Webhook to Blank to Block Voice Calls

We don't advise allowing voice calls on this Twilio number.

On the phone number configuration page, Find:

A CALL COMES IN ->. Webhook: https://demo.twilio.com/welcome/voice/

and delete that URL so the webhook box is blank. This should block voice calls.

Twilio says that With an empty webhook, this phone number is considered 'out of service' for inbound calls. You will not be charged for any incoming calls in this state, nor will these calls be received and logged in your project. Steps for submitting a blank Voice Webhook URL on your on your Twilio number can be found here: Configuring Phone Numbers to Receive Voice Calls - Webhook.

Test the SMS tool on your Live Site

Create the processes need and familiarize yourself with how SMS works on the demo site.

Troubleshooting

Reply Texts are not in the SMS Received Log

Check the phone number configured on the Admin > Telephony & SMS page against your configured phone numbers in Twilio. Look for confusion between your demo and live sites.

Reply Texts are not being associated with Cases

Is there at least one case that has a client phone number matching the number you are replying from? Do a red Search > People for the number you are sending from.
Is your webhook correct in Twilio? Look carefully. One character off, and it will not work.
Is your webhook set to HTTP GET instead of the default HTTP POST?

Page updated

Report abuse