CommCare Messaging Reports
- Amy Cooper
- Gillian Javetski
- Krinda Wernicke
All CommCare Reports
Report: Message Log
The Message Log is a cumulative list of messages sent and received. This is the history of all SMS-interactions.
Go to Reports, and find the Messaging section to access the Message Log.
There are many Types of SMS messages captured in the log.
Broadcast - outgoing message content
Reminder - scheduled messages
Survey - collects data from incoming messages
Keyword - a word or letter that triggers an action in HQ including opening a form, sends a reply, escalates an alert.
Other - messages from an unrecognized source
Default - when CommCare HQ receives a message that doesn't match any of the configured workflows (i.e. keywords)
A single message can be tagged as multiple types. For example, a survey that is submitted as a structured keyword will be tagged as survey and keyword.
Filtering the Report
The report will let you filter to view a specific set of messages. You can filter by:
Date range of the message
Type of message (Broadcast message, keyword, reminder, survey, etc.)
Location
Message Log includes:
Timestamp - date/time from the server (shown in the project's timezone.)
User Name - name of the contact, a case or user
Phone Number - phone number of the phone involved in the interaction
Direction - incoming or outgoing message
Message - the actual text sent out or received in the message
Type of message
After applying the filter you can choose "export to Excel" if you'd like more complex analysis.
Use of the Feature
When investigating Messaging questions, start here.
Notes and Limitations
You cannot delete messages from the message log.
Report: Message History
The Messaging History report allows you to view all of the messaging related activity for a project - it will list any successful and attempted messages to help you troubleshoot and understand your messaging project.
If there was an error in sending the message, the report will show the reason for failure (missing phone number, duplicate phone number, etc.).
To access it, go to the Reports Tab, and go to Messaging, then select Messaging History
Or navigate directly using https://www.commcarehq.org/a/project/reports/messaging_events/
Filtering the Report
The report will let you filter to view a specific set of messages. You can filter by:
Date range of the message
Type of message (Broadcast message, keyword, reminder, survey, etc.)
Status - Completed, In Progress (for two way surveys), Error, Delivered (for email only)
Phone Number for Message
View Message Details
The report will list individual messaging events - an event could contain multiple messages (ex. an SMS survey will contain many messages between CommCareHQ and the participant, but will only be listed once).
View Details: Link to individual event will show the specific messages that are part of that event (and the status of each).
Recipient name: Link to a case data page.
Content: Link to the reminder set-up that triggered the message.
Notes and Limitations
For unsuccessful messages, the report will show the reason for failure (missing phone number, duplicate phone number, email bounced etc.).
For email messages, the message detail report will show if the message was bounced, sent (i.e. the message has left our mail provider), or delivered (the recipient's mail server said the message was delivered).
Report: SMS Usage Report
Use this report to check the activity of mobile workers in your project. This is similar to the standard worker monitoring report.
Filtering the Report
The report will let you filter to view a specific set of messages. You can filter by:
Reporting group
Date range of the message
Use the Report
The report provides a high level summary for each user, with three columns
Messages received
Messages sent
Phone Numbers used
Notes and Limitations
If the mobile worker has never used a phone number, they are also inactive.
Only contacts with verified accounts are included in this report.
Report: SMS Opt Out Report
Use this report to check if a contact has opted out of receiving SMS messages.
If a contact has opted out, they will no longer receive SMS messages under any condition.
Filtering the Report
The report will show Phone Numbers who have used the opt-out workflow, across the life of the project.
The report can exported to Excel where the data can be manipulated more easily.
The report does not link to other pages on CommCareHQ.
Use the Report
The report identifies contacts in a project space who have used the opt-out workflow.
The list of contacts shows the timestamp of their last action and if a contact has accepted to receive SMS.
No, cannot receive SMS. The row will show a time stamp for Last Opt Out Timestamp
To opt out, a contact must text in the word "Stop"Yes, can receive SMS. The row will show a time stamp for Last Opt In Timestamp.
To opt in, a contact must text in the word "Yes"
The user will receive a message,
"You have opted-in to receive messages from CommCareHQ. To opt-out, reply to this number with STOP
Notes and Limitations
You can not filter this report based on standard parameters.
Scheduled Messaging Events
The Scheduled Messaging Events report (available from the Reports tab under the Messaging heading) shows all instances of Broadcasts or Conditional Alerts that are scheduled to take place but haven't been processed yet.
For example, if you create a Broadcast to send an SMS tomorrow at 9:00am to one User and one User Group, you will see two entries in this report scheduled at 9:00am tomorrow (one for each recipient you selected in the Recipients section of the Broadcast). After the SMS sends tomorrow, no more entries will be in this report for that Broadcast because all events will have been processed.
Similarly, for Conditional Alerts, you will see entries in this report for events which are scheduled to take place but haven't been processed yet. There will be an entry in this report for each recipient you select in your Conditional Alert, for each case that matches the Conditional Alert's rule criteria.
Note: You will only see the next scheduled event in the schedule for the Broadcast or Conditional Alert. For example, if you've defined a daily schedule which sends every day at 9:00am, this report will only show the next scheduled event for 9:00am. After this event is processed, the event will be scheduled for the next day and this report will reflect the newly scheduled date and time. Once all events in the schedule are processed, no entries will be shown.
Filters
The first filter you may choose to apply will filter the report based scheduled event date:
Option | Description |
|---|---|
All Events | Not filtering will occur based on scheduled event date. |
Events to be sent after | Only events scheduled on or after the given date (interpreted in the time zone of your project) will be shown. |
In the second filter, choose whether you want to see scheduled events for Broadcasts or Conditional Alerts:
Option | Description |
|---|---|
Broadcasts | Only scheduled events for Broadcasts will be shown. |
Conditional Alerts | Only scheduled events for Conditional Alerts will be shown. Optionally, you can also choose to show scheduled events for a specific Conditional Alert. |
Report Content
The report shows the following information:
Column | Description |
|---|---|
Next Event Due | The date and time (in your project's time zone) that the event is scheduled for. |
Scheduling Configuration | A link to the Broadcast or Conditional Alert which the event is tied to. |
Recipient | The recipient, which could be a Mobile Worker, a Mobile Worker Group, an Organization, a Case, or a Case Group. This will match the recipient configuration of your Broadcast or Conditional Alert and there will be one entry for each recipient you define there. |
Triggering Case | This column only applies to Conditional Alerts. It shows the case that matched the rule criteria of the Conditional Alert which caused the event to spawn. |
Messaging Dashboard
SMS Status
This status can be one of the following values:
Status | Meaning |
|---|---|
Processing Complete | All queued messages have been processed. |
Processing In Progress | There are queued messages which are currently being processed. |
Processing Paused | No messages are currently being processed. Any messages created will remain queued until SMS processing resumes. |
When SMS processing is paused, it's either because 1) you have exceeded your project's daily limit of messages that can be sent per day, or 2) your project restricts the times of day at which SMS can be sent and one of those restrictions is currently active. For the purposes of determining how many SMS are sent per day, the system will consider the 24-hour period starting at midnight in the time zone of your project.
All Messaging Events Status
This status can be one of the following values:
Status | Meaning |
|---|---|
Processing Complete | All due events have been processed. |
Processing In Progress | There are events which are due that are currently being processed. |
Event processing is never paused. If your project's SMS Status is paused, events will continue to be processed and any messages created will remain queued until SMS processing resumes.
Incoming / Outgoing SMS
This chart shows the number of incoming and outgoing SMS for your project over the given time period. Outgoing messages are only counted after being successfully handed off to the SMS gateway for delivery.
Messaging Events (Success / Error)
This chart shows number of messaging events that completed successfully as well as those that had errors over the given time period. Examples of messaging events include: sending due reminders, sending broadcasts, and contacts invoking keywords.
Messaging Event Error Summary
This chart sums all of the errors that occurred with messaging events over the given time period and groups them by error. Hover the mouse over each bar to see the error. Possible error messages are:
Error | Description |
|---|---|
Gateway error. | The SMS could not be handed off to the gateway. CommCareHQ will try handing off to the gateway 3 times, and if the gateway errors all 3 times the SMS is removed from the queue and labeled with this error. |
Phone number has opted out of receiving SMS. | The destination phone number has opted out of receiving SMS. The phone number must opt back in to continue receiving messages. |
The gateway can't reach the destination number. | The gateway is reporting that the destination number is an invalid number. This could mean that the number is missing digits, that it is not formatted properly, or that it references a land line or non-existent phone number. Check that the contact's phone number is entered correctly in international format. Note: Not all gateways will provide this error. |
The gateway could not process the message because it was too long. | The message was too long for the gateway to process. Most gateways support concatenated SMS so the limit is normally very high. |
The recipient has been deactivated. | If the contact is a user, this means the user is deactivated. If the contact is a case, it means the case has been closed. In either situation, CommCareHQ will not send to deactivated contacts. |
No recipient | There is no recipient for the reminder. This can happen, for example, if the reminder sends to a user group and there are no users in the group. |
No message available for the given language settings. | No translation was found in the reminder for the contact's preferred language (or the reminder's default language if the contact has no preferred language). |
Error rendering message; please check syntax. | The reminder message is referencing variables incorrectly. Double-check the reminder message's variable references. |
Gateway does not support the destination country. | The gateway does not allow sending to the destination phone number's country. Double check that the phone number is in international format. If it is, you will need to use a different gateway to send SMS to this contact. |
Contact has no phone number. | The contact has no phone number configured so the message could not be sent. |
Contact has no two-way phone number. | The contact either has no phone number configured, or the phone number is not a two-way number. Two-way numbers are required for using SMS surveys. You can find more information here about registering two-way phone numbers. |
Cannot find form. | The form referenced for the SMS survey could not be found. |
No questions were available in the form. | The form referenced for the SMS survey had no questions or labels. Check that the form has questions or labels and that display conditions are not preventing questions or labels from being displayed. |
The case with the given external ID was not found. | A mobile worker invoked a keyword to start an SMS survey (form) that requires a case and passed an external id which does not reference any case that the user has access to. |
Multiple cases were found with the given external ID. | A mobile worker invoked a keyword to start an SMS survey (form) that requires a case and passed an external id which references more than one case. |
The form requires a case but no case was provided. | This may happen if you schedule an SMS survey (form) that requires a case to a mobile worker using a broadcast. There is no case to be found in this context so you cannot send surveys which require cases. |
No external ID given; please include case external ID after keyword. | A mobile worker invoked a keyword to start a survey (form) that requires a case and did not pass an external id to select the case for which to fill out the survey. |
Error processing structured SMS. | The structured SMS could not be processed because it failed validation, for example if a text response was given to a numeric question type. An error message is sent back to the contact invoking the keyword in this situation explaining what the validation error was. |
An error occurred in the formplayer service. | This error only affects SMS surveys and can happen if the formplayer service is down. If this happens when starting a scheduled SMS survey, it will be retried until it succeeds. If it is an SMS survey started from a keyword, an error message is returned to the contact asking them to try again. |
Internal Server Error Cannot connect to touchforms. | This error affects SMS surveys and can happen if an SMS survey is being sent to a case and the case has no case name. The error causes an immediate delivery failure to the SMS being sent out. |
Gateway could not be found. | The gateway to be used to send the message was not found. This can happen if a contact uses a preferred gateway and the gateway referenced cannot be found. |
Recipient has no email address. | The contact has no email address configured so the email could not be sent. |
An error occurred in the formplayer service. | This error affects SMS surveys and occurs when the form contains 'commcaresession' instances and 'location' instances in the calculation. |
CommCare Messaging Exports
There are two ways of exporting Messaging data via CommCareHQ:
Form Submissions - the record of all SMS survey data
SMS Export - the record of all SMS messages sent and received
To view your SMS data, choose Export SMS in the Data Tab.
Form Submissions
Form submissions consist of SMS survey responses/data and are available through the standard CommCareHQ data interface. You can view these in several places:
Submit History - shows the most recent form submissions
Export Form Submissions to Excel - allows you to choose a specific form and export all of the submissions against that form for a particular date range
For either of these sources, if you are looking at surveys filled out by the case (as opposed to the "user") you will need to chose "Unknown Users" in the Report Filter.
If you are exporting results of an SMS Survey using a form export, go to the Show Advanced Questions option in the Export set-up, and select the property Partial Submission.
If a Survey was started but not completed, the field partial_submission will show TRUE.
SMS Export
A fast way to download the data normally found in the Message Log. Quickly set a date filter, and review it in Excel.
Has the same export format as the Message Log, but is more scalable for large projects
Click here to learn more about the Message Log.
The export is available as a .zip file. It is not possible to edit the column contents.