Thursday, October 15, 2015 - 10:41
Written by

The story so far...

Future First is an ambitious young charity that works with state-funded schools to use their old students to motivate their current students in the same way that privately funded schools do. Way back in 2012, they approached Michael McAndrew, then of Third Sector Design, to produce a system to help them to stay in touch with students who might have changed their email addresses since leaving school. The SMS Survey technology would send messages back and forth to students and then interpret the results into data that could be merged into the profile. Since then their internal software development team - lead by myself - added an interface for easier conversion of responses into data, more robust response detection, and an interface to clean up invalid responses.

FF commissioned me to add some key features to it and, most importantly, put it and our subsequent additions into a releasable state. The work was to be done during the UK 2015 CiviSprint, in beautiful Edale, but more on that later.

What is a release candidate?

A 'release candidate' is unfinished software that we are ready to test with another organisation. In this case, it has only been used by Future First, and may be a bit rough around the edges. Having said that, it has been used several times with tens of thousands of contacts. In short, please don't be upset if it has a bug or two!

What can it do?

It is used to interpret SMS responses into data into your CiviCRM contacts. You can use it to "fill in the gaps" in your data, or to conduct surveys. You need to ask a developer to add the ability to fill in specific fields - our internal software development team can do this from scratch in around an hour.

The release candidate includes functionality to request contacts' Gender and new Email Addresses - ideal for reducing your bounce rate.

The four different pieces of the survey

1. SMS Chains. This is the ability to send follow up messages to a response based on the first message you sent out. So your first message may say "please send us your email address" and then a follow up message could say "thanks for sending us your email address!" This would be constructed using an SMS Chain.

2. The translator. When you've got your responses, it's time to have SMS Survey analyse them and put the output into the different fields. This process is called 'translating'.

3. The cleanup tool. After translating, there will be some messages that don't quite fit (see below for common responses).

4. The swear filter. Depending on your target audience, occasionally, people may respond including language that some may find offensive. The SMS Survey includes an optional filter to prevent these responses from polluting your data (note that their response will still be stored in the Inbound SMS activity created by Civi). You can add words that may be offensive, including a safe list, to this filter.

The different steps

0. Install the extension.

1. Clean your contact data.

2. Write the messages.

3. Construct the chains.

4. Populate the swear filter.

5. Buy SMS credits.

6. Send the messages.

7. Wait!

8. Translate the responses.

9. View the translation cleaner.

10. Re-translate if required.

0. Install the SMS Survey Extension

At the time of writing, the SMS Survey Release Candidate isn't available for automatic installation. Please ask your system administrator to help you here. You can find the release candidate here:

1. Clean your data!

Having 'cleaner' data will make for a more efficient survey. There's two types of data cleaning to be perform here: phone numbers and duplicate contacts. Having invalid phone numbers means that you'll spend credits sending messages that will never reach their destination. Believe me, at FF we've seen people enter all sorts of things into the phone number field! No matter how well intentioned, Clickatell just won't be able to get a text message to "07780000000 (Mondays to Fridays in working hours only)". You can use CiviFirst's handy Phone Number Validator to identify the most glaring errors. Using an earlier version of this tool lead to our response rate leaping by 10%! Afterwards, it's time to deduplicate. You should use the phone number tool first, as this will make you more likely to identify duplicates. 

2. WritE the messages

Future First learned through bitter experience that messages need to be really clear and unambiguous (even then people will respond with bizarrities, see below!). Be sure to use the contact's first name, say who you are, why you need the information, and say that you just need that information. txtspk tends to not be received well. So a good message is "Hi {contact.first_name}! {your organisation name} here. We don't seem to have an up to date email address for you. Please can you text us back just an email address that you'd like us to contact you on? We promise we won't pass it on. Thanks!" A nice follow up one might be "Thanks for letting us know - we'll be in touch soon!".

3. Construct the chains

The SMS Survey tool allows you to construct "chains" of messages. This means that if the user responds, you'll have a follow up message to send them back. You may send them a different follow up depending on what response they send. For instance, Future First asks students who've recently left their school to text back A if they are going to University, B if they are going to College, C if they went straight into work, or D if they are going to do something else.  When they text back either A, B, C, or D, then a new question is sent relevant to that response, either asking them what course they're taking, or asking them what their job title is. Your Translator class will need to account for the different potential branches.

The end of each of your chains should be a message thanking the user for responding.

4. populatE the optional swear filter

Unfortunately, when sending SMS messages to large numbers of people, some may text back including words that you don't want to be automatically added into their contact fields. Although commonly swears, these may include inappropriate slang or epithets.

The SMS Survey includes an optional swear filter, which your organisation will need to populate itself. No swear words or unpleasant language are included with the SMS Survey, and installing the release candidate will not add any into your system in any way.

You will require the 'administer sms survey swear filter' permission, which can only be added by a system administrator to view or edit this list. This allows you to prevent members of staff or volunteers from accessing a list of vile language. Please make staff with this permission aware that they shouldn't share their login details.

A safe list is available to add words that are known to be safe but that contain a word some consider offensive. Those interested should see the 'Scunthorpe Problem'.

5. Buy sms credits

Count the number of people you're going to send the message to. Count how many characters in your message, remembering that around 90% of your contacts' first names will have 7 characters or less. Future First has a typical response rate of around 50%, Clickatell charges 1/3 of a credit per inbound message, and then another message to thank them. This will help you to determine the number of credits you need for the survey. We suggest you buy in bulk, it's usually cheaper!

6. Use New Mass SMS to send the messages as normal

We recommend dividing into groups with different wording for "split testing".

7. Wait!

Future First found that almost all of our responses were in the first 24 hours. By the first 48 hours you're likely to have all the responses you're going to get.

8. Translate the responses.

This is where your contacts' responses to messages are interpreted into your contacts' data fields. In the menu go to Mailings -> SMS Survey -> Translate Responses. In the drop down menu, select the SMS Survey message that you sent. This should populate all the fields that you need. Adjust the dates as you need to - messages outside this window will be ignored. It will populate the groups field accordingly - only change this if you know that you need to (i.e. for a subset of the data).

The Translation Type is the kind of information that we expect from your contacts' responses. You can select 'Gender' or 'Email Addresses', or ask your internal software development team or consultant to make you another one. 
The 'campaign name' is the subject of the created activities. This needs to be consistent across the campaign, so we recommend leaving it as the default (which is the name of the Mass SMS Message).
When you're finished click 'Translate!'. How much time the process takes will depend on how many contacts there are in the group that you're translating. You can then take a look at the statistics by clicking on "View Translation Statistics".
The SMS Survey Translator will create  an activity of SMS Conversation for contacts who've responded to the SMS survey.

9. View the translation cleaner.

Not all messages can be interpreted correctly. This is particularly true of complex surveys. Future First asks respondents to include both their employer and their job title separated by a comma. Often responses contain only one piece of information, or have several commas, meaning that the translator doesn't know how to interpret them.

For survey responses that couldn't be 100% translated, the SMS Conversation will have the the status 'Scheduled' (successful translations have the status 'Completion').

To fix messages that haven't translated correctly, go to Mailings -> SMS Survey -> Clean Translated Responses.

There are basically two options: either edit the response into the contact manually and then mark the SMS Conversation activity as completed, or edit the inbound responses before retranslating.

10. Re-translate after cleaning if required.

After editing the responses, you can retranslate them by following the process outlined in 8. Translate The Responses.

File attachments: 
Image icon translator.png93.15 KB
Image icon stats.png40.87 KB
Filed under