Registering an Individual Contact

Overview

This describes how to setup a form that will register a case (or contact) for use with Messaging.  This form can then be used in a number of ways:

• By a mobile worker to register contacts using SMS
• Through a CommCare phone application
• Through the CommCareHQ web data entry (Using CloudCare).  

Messaging only supports a single phone number in the case.  For example, while you may be able to store both both a mother and husband's phone number in the case, only one of the two will be supported for Messaging. 

Preparation

It is recommended that you complete the Beginner Tutorial and the Basic Case Management Tutorial before running through this.  

Setup

1. Go to Surveys and choose "New Application"
   
   
   
2. Name the application "SMS Surveys".  If you want to enable registration through a web-based application, choose the "CloudCare" option.   Use the green "Save" button.  
   
   
   
3. Choose the "Untitled Module" and rename it to "Surveys" and click the green Save button.
   
   
   
4. Choose the Case Management option and type in a case.  This is the object name for the type of contact that is being registered.  You can use a word like contact or participant.  Once you've specified a case type, click the green Save button.  
   
   
   
5. Click on Untitled Form and rename it to "Registration" and Save.  Once that is done, click on the blue Create button. 
   
   
   
6. You should see the Form Builder. There is a toolbar of potential questions at the top of the screen.  Add a Text question. If you are doing an SMS Survey only text, number, choice and date questions are supported. 
   
7. This question will be used to capture the name of the contact.
   1. Question ID is the variable name for the name.  Just use name. 
   2. Label: This is what will actually be asked on the phone or through SMS for this question.  Set the text to "What is the contact's name?"
   
   
   
8. Add a question to enter the phone number of the contact.  Choose the number dropdown and select Phone Number or Numerical ID.  
   
   
   
9. Set the Question ID to contact_phone_number.  Set the label to "Enter phone number (only numbers with country code)"
   
   
   
10. Add a hidden value to the form with an ID of contact_phone_number_is_verified.  Set the Calculate condition to 1.  (This indicates that the phone number has been verified and is a real number).
    
    
    
11. Save the form (green button in the top right corner).  
12. Select the form in the application builder, then select the Case Management tab.
    
    
    
13. Choose the form type as "Registers a New Case".  Set the name to the "What is contact's name" question and save the other two questions to the case.  Make sure that the case properties are contact_phone_number and contact_phone_number_is_verified.  Make sure you save changes using the green Save button.  
    

Now that the form is created, you can use it to register new contacts, either through SMS (for your field staff), or using a phone number.  

Registering New Users through SMS

A mobile worker (field staff) for your project can register contacts/participants using SMS from their phone.  

1. Follow the instructions to configure a mobile worker to use SMS (Configure a Mobile Worker for Messaging)
2. Create a new keyword (ex. REGISTER) that will run the Registration form you just created. (Setup SMS Keywords)

Registering New users through a Phone or Web-based Application

As CommCare Messaging is a part of CommCareHQ, you can use a CommCare application (or web application) to register users.  Please follow the Application Building Tutorial Series to learn how to build and deploy phone/web based applications.  

Notes/Advanced Configuration

1. All Phone Numbers Must Be Unique.
   If a phone number is shared with another CommCare Messaging-enabled case or verified or a mobile worker (even in another project), messages will not be sent. To address this issue, close at any other cases using that phone number or delete the verified number from the mobile worker. 
2. Verifying a Number
   The example above automatically marks an added phone number as verified. Alternatively, you may have the health worker tries to call or text the user. Once this has been done successfully, they can use a form to set the value of contact_phone_number_is_verified to 1.
3. Advanced Case Configuration
   CommCare Messaging requires a certain set of properties to be included in the case.  
   1. commcare_email_address - This is the email address of the mobile worker for receiving emailed messages
   2. contact_phone_number - This is the phone number to send messages to. It should include the country code (ex. 1 for the USA or 91 for India) and the rest of the phone number. It should not have any spaces, dashes or other punctuation. For example, both "12066181323" and "910981231234" are valid values. "1-206-617-1234" will not work.
   3. contact_phone_number_is_verified - This should be set to "1" to indicate that the phone number has been verified and is a real number.
   4.  [Optional] Contact Back End, Languages and Time Zones

      [optional] time_zone - This specifies the time zone of the phone number. If messages are sent to the case at a particular time, this time zone will be used. Otherwise, UTC will used. For example, to set US East Coast Time as the time zone, this should be set to "America/New_York". A full list of available time zones can be found by going to Project Settings and viewing the list available for "Default Timezone". 

      [optional] language_code - For an SMS survey available in multiple languages, this specifies which language to use when running the survey. This should match the language codes specified when defining the application on CommCareHQ. For example this would be set to "en" for English or "hin" for Hindi. 

      [optional] contact_backend_id - This specifies which SMS provider to use when sending SMSs to the number. This is normally done once for a project. In advanced situations, you may want to have different gateways for each contact. Please see Setup SMS Connection for Project to view the list of available gateway options.