Building SMS Schedules

Building CHT application SMS schedules

SMS schedules allow you to send reminder messages at predetermined times. These reminders serve as useful prompts for end-users to take specific actions.

This tutorial takes you through how to set up SMS schedules for CHT applications. It uses a pregnancy registration workflow and follow-up reminders for a Community Health Worker as an example. The same methodology can be applied to other workflows and reminders as needed.

Brief Overview of Key Concepts

SMS schedules are a series of SMS messages that are to be sent to specific contacts at future dates and times. They are defined in either the base_settings.json or the app_settings/schedules.json file and compiled into the app_settings.json file with the compile-app-settings action in the cht-conf tool.

SMS schedules can be triggered by SMS forms or App forms.

Required Resources

You should have built a pregnancy SMS form.

Implementation Steps

SMS schedules are defined using JSON in the app_settings.json file.

1. Define a Pregnancy Follow Up Schedule

To set the pregnancy follow up schedule, edit the array corresponding to the schedules key in app_settings.json. Add an object within the array as shown. This will set a schedule of reminders that will be sent after a time interval (offset) relative to a base date (start_from).

schedules: [
  {
    "name": "Pregnancy Follow Up Reminders",
    "summary": "",
    "description": "",
    "start_from": "fields.lmp_date",
    "messages": [
      {
        "message": [
          {
            "content": "Hello {{contact.name}}, please remind {{patient_name}} ({{patient_id}}) to go for her clinic visit this week.",
            "locale": "en"
          }
        ],
        "group": 1,
        "offset": "23 days",
        "send_day": "",
        "send_time": "09:00",
        "recipient": "reporting_unit"
      },
      {
        "message": [
          {
            "content": "Hello {{contact.name}}, please remind {{patient_name}} ({{patient_id}}) to go for her clinic visit this week.",
            "locale": "en"
          }
        ],
        "group": 2,
        "offset": "51 days",
        "send_day": "",
        "send_time": "09:00",
        "recipient": "reporting_unit"
      },
      {
        "message": [
          {
            "content": "Hello {{contact.name}}, please remind {{patient_name}} ({{patient_id}}) to go for her clinic visit this week.",
            "locale": "en"
          }
        ],
        "group": 3,
        "offset": "79 days",
        "send_day": "",
        "send_time": "09:00",
        "recipient": "reporting_unit"
      },
      {
        "message": [
          {
            "content": "Hello {{contact.name}}, please remind {{patient_name}} ({{patient_id}}) to go for her clinic visit this week.",
            "locale": "en"
          }
        ],
        "group": 4,
        "offset": "107 days",
        "send_day": "",
        "send_time": "09:00",
        "recipient": "reporting_unit"
      }
    ]
  }
]

See Also: Schedule properties

2. Assign the Schedule

In the registrations array where you have defined the pregnancy registration events, add an event to assign the Pregnancy Follow Up Reminders schedule. This will assign a new schedule for every pregnancy that is registered.

{
  "name": "on_create",
  "trigger": "assign_schedule",
  "params": "Pregnancy Follow Up Reminders",
  "bool_expr": "doc.fields.lmp && /^[0-9]+$/.test(doc.fields.lmp)"
}

The final result should look like this:

"registrations": [
  {
    "form": "P",
    "events": [
      {
        "name": "on_create",
        "trigger": "add_expected_date",
        "params": "lmp_date",
        "bool_expr": "doc.fields.lmp && /^[0-9]+$/.test(doc.fields.lmp)"
      },
      {
        "name": "on_create",
        "trigger": "assign_schedule",
        "params": "Pregnancy Follow Up Reminders",
        "bool_expr": "doc.fields.lmp && /^[0-9]+$/.test(doc.fields.lmp)"
      }
    ],
    "validations": {
      "join_responses": false,
      "list": [
        {
          "property": "patient_id",
          "rule": "regex('^[0-9]{5,13}$')",
          "translation_key": "messages.validation.patient_id"
        },
        {
          "property": "lmp",
          "rule": "lenMin(1) ? (integer && between(4,42)) : optional",
          "translation_key": "messages.p.validation.weeks_since_last_lmp"
        }
      ]
    },
    "messages": [
      {
        "event_type": "report_accepted",
        "translation_key": "messages.p.report_accepted",
        "recipient": "reporting_unit"
      },
      {
        "event_type": "registration_not_found",
        "translation_key": "messages.validation.woman_id",
        "recipient": "reporting_unit"
      }
    ]
  }
]

3. Upload App Settings

To upload app settings to your local instance, run the following command:

cht --url=https://<username>:<password>@localhost --accept-self-signed-certs upload-app-settings

Frequenty Asked Questions

Related Content

CHT Applications > Reference > app_settings.json > .schedules

SMS Schedules: Defining SMS workflows with schedules, registration, and patient reports.

CHT Applications > Concepts > Forms

Building block for all CHT apps

CHT Applications > Features > Messaging

Messaging for Care Coordination, Alerts, and Notifications

CHT Applications > Quick Guides > Messaging

Building and troubleshooting messaging


Last modified 16.07.2021: Update references from medic-conf to cht-conf (#529) (8879b500)
Edit this page Create documentation issue Create project issue