CommCare Messaging lets you send scheduled or immediate messages to a group of recipients (either a set of Mobile Worker Groups or Case Groups).  

What makes Broadcast messages different than conditional alerts or keywords?

Broadcast messages are simple reminders, and do not use case properties as triggers. 

To send messages in bulk, click on Messaging > Broadcasts

When are Broadcast messages useful?

• To set-up and schedule simple messages. 

• To contact all users in a one group with one time feedback after a day of supervision. 

• To send a meeting reminder, that is copied on an irregular basis. 

Creating a New Broadcast

Click on the + Add Broadcast button 

Set-up the key information 

• Who is the recipient?  Do you want to send this a Mobile Worker Groups, Case Groups or Locations.  

• When should the message be sent? Specify the timing, either send a message immediately, or at a later date.  

  • If the broadcast messages is sent at a later date, the time must be specified in 24 hour format.  

  • The project's timezone will be used.

• What do you want your message to say? Remember mobile worker groups cannot reference case properties. 

Open

Send an SMS message or SMS survey.

• If sending an SMS message to a case group, you can specify case properties using {case.case_property}.  For example, you may send the message "Thank you participating in this survey.  Please contact {case.correspondent} if you have any questions."

• If sending an SMS survey to a mobile worker group, the selected survey cannot update or close cases.  The broadcast will fail to send if this is selected. 

Review Scheduled Broadcast Messages

After you create a Broadcast Message, go to the Scheduled Broadcasts section on the Broadcasts page to view or edit all upcoming scheduled messages.

To edit the scheduled broadcast, click on the relevant name under the "Name" column.

To delete a scheduled broadcast, click on the red X button, once you do you will need to confirm the deletion on the pop up.

To either active or deactivate, click on the relevant button under the "Action" column.

Open

Grouping Cases

CommCare Messaging allows you to group cases (contacts) to allow broadcast surveys or messages, similar to a mobile worker group.

When to Use a Case Group

Case groups are most useful in combination with Broadcast messages.

Often they can be used to communicate with cases in a specific region, or a subset of patients. 

For example,

1.  A case manager wants to easily communicate with the 20 participant cases under their supervision. 

2.  Notify all participants in a study of a particular side effect. 

3.  Alert all HIV+ participants that a new service is available.  

Creating a Case Group

1. Go to Messaging > Case Groups

2. Type in the name of your group (ex. Patients and click the "+ Create Group" button.

3. Click on the Group Name link to edit the cases within the group.

Add cases to the Case Group manually with an identifier

This approach allows you to add individual cases to a case group.

Type in an identifier for the case (phone number, an external ID specified when creating case or the actual case ID).  

1. If specifying the phone number, you need to specify the full phone number (including country code with no spaces and no + symbol).  

2. The case ID can be found through the page for that case, or a case export. 

Then click on the + Add Case button.  If the case can't be found, an error will be displayed. 

Note: To link back to the case data page, select the case name. 

Bulk upload cases to a case group

Select the link and download the excel template, named "cases_bulk_example.xlsx" file.  

Open the sheet, and you will find a column header name case_identifier.

In the file, type each case to add to the group as a separate row.  You can use the phone number, external ID or the actual case ID.  The case ID can be found in a case export or on the individual case_data page. 

Upload the new list to add contacts to the case group.

Note: If the case can't be found, an error will be displayed. 

Note: All cases in a Messaging Case Group must have a valid contact_phone_number, including the country code. 

Editing a Case Group

Use the Manage Cases button to open the Case Group.  

You can use the + Remove button to remove cases from the group and the + Add Case button to add additional cases.  

You can can also using the Excel import functionality to bulk add phone numbers.  

If you want to remove all cases from the group, its easiest to delete the group and create it again.  

Broadcasts

Broadcasts are the simplest way to schedule one-time or recurring messages to your contacts. Creating a broadcast is a matter of defining the sending schedule, the recipients, and the content to send. Below each section of the page is described in greater detail.

Active

At the top of the page you can choose whether your broadcast is active or not. Activating / deactivating it here or on the broadcast list page has the same effect.

Scheduling

First, choose a Schedule Name so that you can pick this broadcast out in the broadcast list in case you need to make changes to it later. Next, choose a schedule frequency next to the Send label. The different frequencies and their options are described below.

Immediately

Immediate schedules will send the content one time to the recipients and stop. These types of broadcasts can't be modified later because of their one-time nature and must always be created as Active. 

Daily

Choosing a daily schedule allows you to send the content one or more days at specific times. Below are the options for configuring a daily schedule:

Some examples of setting up different daily schedules:

Send one time on 2018-04-15 at 12:00pm

Send every day at 9:00am

For the month of April 2018, send every other day at a random time between 12:00pm and 1:00pm

Weekly

Many of the options for the weekly schedule are the same as the daily scheduling options, only that now you must select the days of the week on which to send.

The following options have new meanings:

Some examples of setting up different weekly schedules:

Send every Monday, Wednesday, and Friday at 12:00pm for the first 4 weeks of April 2018:

Send on Tuesdays and Thursdays at 12:00pm for the first week of April 2018 and the third week of April 2018

Monthly

Many of the options for the monthly schedule are the same as the daily scheduling options, only that now you must select the days of the month on which to send. In addition to choosing a specific day of the month, you can choose the last day of the month, the second to last day of the month, or the third to last day of the month.

The following options also have new meanings:

Some examples of setting up different monthly schedules:

Send on the 15th of every month at 9:00am

For 2018, send every quarter on the first of the quarter, at 9:00am

Send annually on the first of January, at 9:00am

Custom

If your use case is more complex than the default scheduling options, you also have the option of sending a Custom Daily Schedule. See https://dimagi.atlassian.net/wiki/spaces/commcarepublic/pages/2143950732 for more information.

Recipients

When choosing recipient(s) for the broadcast, first choose the recipient type(s). After choosing a type you can choose recipient(s) of that type. Below each recipient type is described in greater detail.

Users

This recipient type allows you to select Mobile Worker(s) to be the recipients of the broadcast.

User Groups

This recipient type allows you to select Mobile Worker Group(s) to be the recipients of the broadcast. All mobile workers assigned to the group(s) you specify will be recipients.

User Organizations

This recipient type allows you to select Organizations and send to all Mobile Workers and Web Users assigned to those Organizations as their primary organization assignment. This recipient type does not send to Cases.

With this recipient type, you also have some additional options. You can send to all Organizations which are descendants of the selected Organizations by selecting the "Also send to users at organizations below the selected ones" option. Further, with that option enabled, you can also choose to only send to specific Organization Levels that are below the selected Organizations. Below are three examples which demonstrate the different options. For the purposes of the example, imagine an Organization hierarchy with 3 levels: Country, State, and City.

Send only to users assigned to Organization USA and no users below that Organization.

Send to all users assigned to Organization USA as well as all users assigned to all State and City Organizations below it.

Send to all users assigned to City Organizations below Organization USA, but do not send to users assigned to the USA Organization or any State Organizations below it

Case Groups

This recipient type allows you to send to Case Groups, a type of grouping of cases that only applies to Messaging use cases. Case Groups are defined on the Messaging > Case Groups page.

Note: Support for Case Groups as recipients might not be available forever. Consider using a Conditional Alert to reach Case contacts, which is a more efficient way of expressing that use case.

Content

In this section you choose what will be sent to the recipient(s) when the schedule's events come due.

SMS

When sending SMS, type the message to send to the recipient(s).

You may also choose to specify translations for the message by checking the "Translate this message" box, in which case the translation to send will be chosen based on each recipient's preferred language. The languages available for use with messaging for your project are defined on the Messaging > Languages page. If the recipient's preferred language does not appear in the list of translations, then the translation associated with Default Language specified in the Advanced section will be used.

Email

When sending Email, type the subject and message of the email to send to the recipient(s). See the SMS section above for more information about specifying message content.

SMS Survey

If your project has access to Inbound SMS, then you will see an option which allows sending SMS Surveys to your recipient(s). An SMS Survey is a Form (defined in the App Builder) which gets filled out over SMS by your recipient(s). At the scheduled time, the SMS Survey session will start and the first question in the Form will be sent to the recipient(s), allowing them to answer the Form one question at a time. Upon completing the survey, the Form will be submitted and any case actions will be applied, just as if the form were submitted over Web Apps or through CommCare Mobile. The following additional options apply when sending SMS Surveys:

Advanced Survey Options

When sending SMS Surveys, these two advanced options are available:

Advanced

The following advanced options are available: