SMS integration for REDCap

What is REDCap

REDCap (Research Electronic Data Capture) is a secure web application designed to support data collection for research studies. The application offers both database building and online surveys, making it ideal for a wide range of data-driven projects.

REDCap is particularly recognized for its flexibility in handling complex data collection strategies and its ability to adapt to different research needs. The system also ensures data integrity with comprehensive audit trails and has user rights management to protect sensitive information.

Developed at Vanderbilt University, REDCap is used globally in more than a hundred countries, emphasizing its reliability and effectiveness.

REDCap and SureSMS

The integration between REDCap and SureSMS takes place via the service we call mail-to-sms in SureSMS. This means that REDCap generates emails that SureSMS sends out as SMS messages to the recipients in REDCap.

In REDCap, SMS can be used to optimize communication through the Automated Survey Invitations and Alerts and Notifications features. This allows users to set up emails that automatically convert to SMS messages, improving response rates and ensuring timely information. These features make it easy to keep participants updated and engaged in research projects.

Before you get started

You may want to consider the following points before you get started:

Do you need to be able to reply to the SMS message? Expand

There are two ways to send SMS messages. One is with a phone number as the sender and the other is with a text as the sender. If you choose to send with a phone number, the recipient can reply to the SMS message. If you choose to send with a text, the recipient cannot reply to the message. You've probably tried getting an SMS from SMS-Service, the hairdresser or similar. These cannot be replied to. If you decide to send with a text (which most REDCap users do), you must choose a sender name.

What should the sender name be? Expand

You need to choose a sender name for your SMS messages. Here the international SMS protocol limits you to 11 characters including spaces, hyphens, periods, etc. Try to come up with a name that makes the recipient associate it with your research project. If you send links in your messages, users are more likely to click on the link if they believe that a credible source actually sent the message.

How will you pay for the service? Expand

You have two options for payment:

Payment via credit card

By choosing online payment by credit card, you deposit an amount into your SureSMS account. Every time you send, we deduct the amount of the SMS from your balance. When your balance reaches the alert level set up (default is 10 DKK), you will receive an email. You can also enable automatic refueling. You will automatically receive an invoice when you have paid.

Payment by invoice/EAN

You can also choose to pay by invoice. Every month we will send you an invoice for last month's usage. The invoice can either be sent via EAN or by email. Note: for invoices, there is a minimum amount of DKK 100,- per month.

How much does it cost?

When you use SureSMS, it costs a small amount for each SMS you send, starting at 0.28 DKK per SMS sent to Danish numbers. Please note that an SMS can only be 160 characters. (read more about prices here.)

There is no setup or ongoing fee. However, it costs at least DKK 100 per month if you want to receive invoices via EAN.

If you want to receive SMS replies, you need to have a two-way solution . It has a subscription fee of 99,- DKK per month.

How to set up REDCap and SureSMS

The integration between REDCap and SureSMS requires setup in both systems. You need to start by setting up SureSMS, then move to REDCap and set up the final touches.

Setup in SureSMS

To use SureSMS from REDCap, you need a SureSMS account and you need an API key from SureSMS. Below we go through the steps you need to go through to set up SureSMS.

Create an API key

1. Login to your SureSMS account here https://app.suresms.com
  If you don't have an account, you can create one here Create SMS Gateway account

1. Select API keys in the menu

1. Click Options in the top right corner and select "SureSMS API key" from the menu.

1. In name you can write e.g. REDCap

1. Click on Save

1. Copy the new API key so you have it for later use.

Set sender name

1. Select Settings -> Sender name from the menu

1. In the top right corner, click "Options" and then click "Order new alphanumeric sender".

1. Fill in the field with the desired sender name and click "Order"

1. Sender name approval is manual and can take up to 24 hours to be approved (typically within an hour)

1. Once the name is approved, return to this page and check the "Is default" tick box

Create payment

Your account has 50 free SMS messages when it is created. All messages sent with a test account end with a sentence stating that it was sent from a test account. To set up payment, click the big red button at the top that says "TEST ACCOUNT". Then follow the instructions to switch to a production account.

Now you're done in SureSMS and can move to REDCap.

Setting up REDCap

We have created a guide for setting up REDCap in PDF. It can be downloaded Survey distribution through sureSMS within REDCap guideline.

Testing the setup

In the process of testing your setup, several things can go wrong.

REDCap does not send an email to SureSMS
SureSMS receives the email but cannot associate it with your account
SureSMS can associate the email with your account but cannot deliver the SMS message

REDCap does not send mail to SureSMS

You must first check that REDCap has sent the message correctly. To do this, open the "Notification log" tab and look at the sent messages:

Here you need to pay special attention to whether the message has been sent at all, who the recipient is and whether there is anything in the text. The recipient in particular can be problematic. The important thing is that it says phone number.apikey.[dinapikey]@2sms.nu. As long as there is content in the message, it should be sent. You can always correct the content afterwards.

SureSMS does not receive mail

If SureSMS receives an email but can't associate it with an account, it will not be sent out as an SMS. This is the hardest problem to find. This is because the SMS message is not added to your SureSMS account - precisely because we can't find it. Typically, this happens because the recipient of the email is not set up correctly.

Take a good look at the Recipient field in the Notification Log. The format should be a plus, followed by the country code and then the phone number. Then either APIKey or your username and a period. Then your SureSMS code or the APIkey you use. The email address should end with @2sms.nu.

Check that there are no semicolons, square brackets or soft brackets in the recipient name.

Try using your regular mail client to send to a recipient name you have copied from the recipient list. If you succeed, it is because REDCap cannot send the email to us. You can test if your username and password are correct by logging in to https://app.suresms.com.

SureSMS receives mail but does not send SMS

The last step in troubleshooting is to see that SureSMS is receiving the email but not sending the SMS message. You can check this by logging in to https://app.suresms.com and click Messages in the menu and then Outbox. In the outbox your SMS will appear, but it will have a status that is not "Delivered". By moving your mouse over the status you can see what went wrong.

Typically, it's because the country code is wrong. It can either be that the number has two country codes - i.e. +454512345678 or that there is no country code at all. It could also be that the link in the message has been "caught" by our SPAM filter.

Please note that SureSMS will not send the same message to the same recipient within 10 minutes. In this case, it will have the status SPAM. You can avoid this by slightly changing the text you send.

Problems with line breaks

When REDCap sends the message, it is sent in HTML. This is with many different codes. SureSMS removes these codes and tries to create a plain text SMS. In particular, REDCap can make line breaks in several ways and this can cause problems. If you can't get REDCap to make a line break, try typing <br> where you want a line break. If you want two line breaks right after each other, try using the code <br2>.

Line breaks count as one character in the SMS, so don't count the four or five characters of code when calculating the length of your SMS.

Once you have set it up and checked that the SMS message looks as it should, you can log on to https://app.suresms.com, find the message and click on Info next to the message. Here you can see how much it costs and how long it is.