Creating the content
This section covers creating the content of the SMS service and how to define the interactions between the SMS recipients and the system.
Form creation
The first step to creating the service content is creating a Form. A form manages the flow of information to and from the service, and in this case visualize that each SMS sent and received is like filling out a field in a form. The logic embedded in the form drives the system reponse and captures the data from the user.
To create a form, first you need a project space and an application.[RH1] This is covered here [LINK]. The process for creating an SMS form is very similar to creating any other data capturing form, with some important differences:
- Data captured and sent can only be numbers, letters, or free-form text. You cannot capture a picture, GPS location or a barcode via SMS.
- Messages to and from the system may be limited to 160 characters or less, or broken into multiple messages depending on the gateway configuration and restrictions.
Creating a form using the form builder interface allows for easy creation and modification of content as shown in the screen capture below:
[INSERT SCREEN CAPTURE OF SMS FORM BUILDER]
Next we will discuss how the form is connected to the SMS system.
Keyword interaction
One way to interact with the form you just created is to assign it a keyword. This keyword will start, or “fire” the form when received from an SMS user. For example, in this case we can create the keyword “SURVEY” and then when an SMS user texts in the words “SURVEY” the form we just created will initiate. This type of form initiation only works for users that are already pre-registered with the system – that is, their phone number is known by the system.
...
To create an SMS information service, you need to define a keyword that the user can text (ex. INFO) and a form (survey) that manages the interaction with the user. For this example, we're going to create a brief form that provides participants in a study with information about the medical trial and content. Users will send in the keyword INFO and will receive a set of options asking them what they need information on.
Form Creation
You need to define a form (or survey) that controls the interaction flow with the user. You can visualize each question or label in the form as an SMS sent and received from the phone. You can use logic in your form to drive how workflow.
Review the instructions here on creating a form for CommCare Messaging (SMS Survey). Some things to think through when building your form:
- SMS Surveys only support text, number, date or choice questions. You can't capture pictures, GPS locations, etc.
- Limit your messages to 160 characters or less. Some phones don't handle longer messages (and will have the content split into multiple messages).
Create a form and name it Information Form. Add a question titled "Which information?" with the options titled Medical Contact, Contact Study Staff and Leave Study.
Now we will add labels that provide the right information for each option. The text for the labels is "Please call Dr.Ravi at 19995551432", "Contact us at 18001321234" and "Text LEAVE if you want to stop study".
We also want to each label to only display based on the option chosen. We can do this using Display Conditions. Display conditions control whether a particular question is shown based on the answer to previous questions. Choose a label, go down to the Logic Section and hit the Edit button on Display Condition. You can then drag and drop questions from the left tree to setup the logic. An example is shown below:
Once you've setup the expression, Save and create similar logic conditions for each of the other labels. Once you're done, choose the green Save button in the corner of the form builder.
Keyword interaction
Once you've built your form, you want to set it up to run when the keyword INFO is sent in. This will start sending questions back to the person who sent in the keyword. Once they respond, the next question or label in the form will be sent back to them.
A keyword is managed or created from the Messaging section of the CommConnect CommCare Messaging site and clicking “Keywords”. [ADD SCREENSHOT] Keywords can be added, deleted, and edited. There are a number of standard and advanced features for keywords that allows for specific control of the keyword operation and functionality.
[OUTLINE KEYWORD FEATURES HERE AND ADD SCREENSHOTS]
User registration
To add users to the system, CommConnect has a User Registration section of the site. While there are several types of users in the system, only two are able to interact with the system via SMS: Mobile workers, and SMS recipients (called “Cases”). The reason for the difference is that Mobile Workers have access to a different set of functionality than SMS recipients or Cases. One example of the different functionality would be giving the Mobile Worker the ability to administer a survey for someone else, collect the data and even register their phone number in the system. The system can then track the performance of the mobile worker over time.
Mobile Workers are added via the Users section of the CommConnec site, and then selecting Mobile Workers. [CONFIRM THIS AND ADD SCREENSHOT] The mobile worker has an optional phone number that can be added and verified, and this process ensures that the Mobile Worker and their phone number are registered to interact with this domain only. The number can be removed and added to another domain later on, but only active for one domain at a time.
SMS recipients, or Cases are added in several ways. One way is to create a registration form, very similar to the form we created above, with the end result of creating a Case in the system with some requisite information included: the phone number of the user and whether or not the phone number is verified with the system.
Another way to add a SMS recipient or Case to the system is to allow for self registration of users. This means a user can text the system keyword “JOIN [domain]” to the system and join the name of the domain in brackets. For example, sending “JOIN PREGNANCY-REMINDERS” would enroll you in the pregnancy reminders project.
Lastly, users can be registered via a bulk upload operation via excel as described here. [LINK TO BULK UPLOAD]
Create a simple keyword called INFO that will simply reply with the form you created to the user. There are some options on the keyword page that are a bit more advanced (will let you send a message to someone else when the keyword is sent in, or collect additional data in the same message as the keyword). These are not needed here. Once you've setup the keyword, hit the Save button at the bottom of the page.
User registration
Users will need to be registered before they can interact with the system. There are two types of users who can interact with the system - contacts who are registered (cases) or mobile workers. Mobile workers are project staff who can use the system via SMS (ex. registering participants). Cases are just contacts registered with the system (ex. study participants). Depending on your use case, you may need to use setup cases, mobile workers or both. Details on how to register users are provided below.
- Bulk Registration of Contacts - This can be used to register a number of contacts using Excel.
- SMS Self Registration - This allows contacts to register for the system on their own.
- Registering a Case Contact - This allows project staff to register contacts using SMS, a phone or web data entry (CloudCare)
- Configure a Mobile Worker for Messaging - Mobile workers need to be verified before they can send in messages to the system.