Running a SMS-based study with Twilio and IronWorker

Back in November I had to run a study that tested a method of habit formation. I didn’t want my participants to know what I’m doing – if they knew I wanted them to develop a new habit, they could put more effort into that and it could bias my results. So instead I told them I was interested in their eating habits. For 4 weeks they were supposed to text me what they had for lunch while I sneakily measured how quickly they develop a texting habit.

I recruited 133 participants who were randomly assigned to one of 6 conditions. Each day they had to let me know what time they had lunch and what they ate. 44 participants had to send their reports in response to a SMS reminder and 66 participants received an automatic confirmation messages after they sent their lunch reports (22 people received both reminders and confirmations). 23 participants were in the control group, so it was up to them what they did, although they still had to text me every day.

Assuming perfect participation (which never happens!), I was going to receive 133 text messages every day for 4 weeks – 3,724 messages in total. I was also going to send 1,232 reminders and reply to 1,848 reports with a cheesy thank you message. Yikes! I was planning to use my own phone and some SMS scheduling apps, but fortunately a colleague did these calculations and pointed out it wouldn’t be very smart. So I decided to dust off my programming skills and do some coding for the first time in years.

Managing text messages with Twilio

I used Twilio to manage text messages. They provide an API for receiving and sending text messages and are incredibly cheap: phone numbers cost $1 each, receiving messages costs $0.02 and sending them costs $0.04. Considering I have a pay-as-you-go phone and don’t have free text messages, that saved me fortune.

I bought two numbers: one handled random automatic responses and the other was for participants who were not supposed to receive any messages from me. I used basic code provided by Twilio to manage automatic responses and added an array with confirmation messages, which were later randomly selected. After the pilot study I also added a short delay before the responses were sent, because instant confirmation messages were freaking people out a little. I ended up with this code:

<?php

     //Participants who should receive confirmation messages
     $participants = array(
         "+44XXXXXXXXXX" => "Name Surname",
     );

     $replies = array(
          //A list of responses to be sent to participants with a few examples:
          "You're brilliant, thank you!",
          "Thank you!",
          "Cheers!",
          "Thanks, you're a star!",
     );

     //Delay to make sure the responses don't arrive at once
     sleep(7);

     //Code for sending the messages
     header("content-type: text/xml");
     echo "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n";
?>
<Response>
     <Message><?php echo $replies[array_rand($replies)]; ?></Message>
</Response>

The only way to stop participants from receiving automatic response was to use an empty message. It’s not the most elegant solution, but I’m lazy and it does its job:

<?php

     //Participants who should NOT receive confirmation messages
     $participants = array(
         "+44XXXXXXXXXX" => "Name Surname",
     );

     //Making sure participants don't receive an autoreply
     header("content-type: text/xml");
     echo "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n";
?>
<Response>
     <Message></Message>
</Response>

Scheduled reminders

Setting up reminders proved to be a little bit more complicated. To do that, I needed a process running on my server to fire up reminders at a specific time and since I haven’t touched servers and their settings for at least 6 years, I wasn’t very keen to suddenly do that. So I used IronWorker to trigger my Twilio code. It was free and surprisingly easy to use, with everything nicely explained. All I needed was this Twilio code:

<?php

     //directory with twilio API files
     require "twilio-php-master/Services/Twilio.php";

     //my account details
     $AccountSid = "XXXXXXXXXXXXXX";
     $AuthToken = "XXXXXXXXXXXXXXX";

     $client = new Services_Twilio($AccountSid, $AuthToken);

     //list of participants who needed a reminder
     $reminderGroup = array(
          "+44XXXXXXXXX" => "Name Surname",
     );    

     //since some people needed reminders and autoreplies, I needed two lists
     $reminderAndConfirmationGroup = array(
          "+44XXXXXXXXX" => "Name Surname",
     );

     //each group used its own Twilio number
      sendsms($reminderGroup,"+44XXXXXXXXXX",$client);
      sendsms($reminderAndConfirmationGroup,"+44XXXXXXXXXX",$client);

     //that's a deafult Twilio funtion for sending messages
     function sendsms($phonebook,$twilionumber,$client)
     {
          foreach ($phonebook as $number => $name)
          {

               $sms = $client->account->messages->sendMessage(

                    // Twilio number (Sender)
                    $twilionumber,

                    // Sent to
                    $number,

                    // SMS Content
                    "Please send your lunch report"
               );
          }
     }

…and this Ruby script specifying which file will be executed by the worker:

         # define the runtime language
          runtime "php"

          # exec is the file that will be executed:
          exec "study_reminder_worker.php"

          # directory where the Twilio API files were saved
          dir "twilio-php-master"

After uploading it to my account I just needed to set up the schedule for reminders. Scheduling options were a bit limited though. I needed reminders at 14:30 on weekdays and 15:30 on weekends, so I had to set up several separate recurring reminder schedules, but overall setting everything up was quick and rather effortless.

If you want to run a study that requires sending or receiving SMS (or both!), the Twilio + IronWorker combo is a great solution. It’s easy to set up and affordable. One of my colleagues already re-used my code to run her study (although she triggered her messages manually) and was quite happy with the tech. So yay for Twilio and iron.io :-)

~falka, 2014-02-17 16:17