How to send text messages (SMS)

Sending text messages via formr

To support a wide variety of providers, we simply provide R functions which will "call" the respective text messaging providers and transmit your text. This way, you can implement similar functions for other providers and aren't tied to the ones we use.

To send a text message via formr using Clickatell, follow these steps:

1. Create a Clickatell account. It’s important that you have access to the Developers’ Central platform, thus, if asked, choose the developers account over a "normal user"-account.

2. You have to create a REST API: Within the Clickatell-Developers’ Central select "APIs - Set up a new API" and "Add REST API". You have now added a REST API with an authentication token that consists of a sequence of characters and numbers. If you didn’t copy the token directly you can find a list of all generated APIs under "APIs - Manage APIs". If you click on "Info and Help" you will find the authentication token.

3. In formr, add an "External" module to your run (at the position where you want your text to be sent).

4. Now you have two options:

   1. a) If you want to keep retrying to send a text message if there is an error, write this into the box:

      ! text_message_clickatell("49163777848484", 
         paste0("Hi dear user, please take part in our study again: https://formr.org/YourStudy/?code=",
         survey_run_sessions$session), 
         "Your_Provider_Token");

   2. b) If you'd rather try only once (maybe because you're not sure the number is right, etc.), write this into the box:

      text_message_clickatell("49163777848484", 
         paste0("Hi dear user, please take part in our study again: https://formr.org/YourStudy/?code=",
         survey_run_sessions$session), 
         "Your_Provider_Token"); 
      FALSE

      Explanation for a/b: To formr, if the script inside "External" returns true it understands "keep trying to go there", if it returns false it understands "done there, go on here". The R function of course returns true on success, false on failure (and the ! inverts that).

5. Change "49163777848484" to the variable, that contains the numbers of your participants, e.g. contact$mobile. You can also start with changing it to your own number to try if your SMS-module works. Either way, this is where you define who receives your message.

6. "Your_Provider_Token" is the token we created in step 2.

7. Your final SMS-module could look similar to this:

   text_message_clickatell(contact$mobile, 
      paste0("Hi dear user, please take part in our study again: https://formr.org/YourStudy/?code=",
      survey_run_sessions$session), 
      "asfjhKffhzFJH_KFHSHkdfha_zlahgjzFH_FSzjhfSJHzKJSzjhzFHKJDKJSFbbchdfh"); 
   FALSE

Of course you don't have to use Clickatell. Install the formr R package and experiment with the other providers and look up how to use them with ?text_message_twilio() or ?text_message_massenversand(). You can also examine the code to see how such a text message providers is called using R and maybe adapt it to your own needs. Below you can see a sample script for Clickatell.

Little problems

If you want to use "special" (e.g. üäö, not in the GSM character set) characters, Clickatell will make things difficult for you. You can use UTF-8, but then a text can have only 70 characters. It's technically possible in principle to get 160 characters and send regional characters, but Clickatell doesn't do that.

Clickatell

library(httr)
To = "492222" # retrieve the stored phone number, you would use something like survey$mobile_number
Body = paste0("Hey, click this link: https://formr.org/YourStudy/?code=",survey_run_sessions$session )
Token = "Tokentokentoken"
result = POST(
    "https://api.clickatell.com/rest/message", 
    verbose(), # so you can see what is happening
    add_headers(
	"X-Version" = 1,
	"Content-Type" = "application/json",
	"Authorization" = paste("Bearer", Token),
	"accept" = "application/json"
	), 
    body = paste0('{"to":["',To,'"],"text":"',Body,'"}')
)
(result2 = content(result))

if(is.null(result2$error_code)) { FALSE } else { TRUE }