SMS message states

Overview of the possible states of SMS messages

Interaction with SMS providers

Medic can use medic-gateway and third party aggregators to send and receive SMS messages.

When an SMS report comes in from a user, medic-sentinel adds the appropriate list of scheduled messages (to be sent at a future date) to the report doc.

Periodically, sentinel checks for messages that need to be sent, and sets their state to pending if their scheduled sending time has been reached or passed.

Periodically, the aggregator checks for messages that need to be sent (i.e. that are in pending state).

The aggregator also reports on the status of the messages it’s sending.

Message statuses/states

Both webapp and the aggregator store states/statuses of the messages to keep track of the exchange. They each have their set of statuses, which sometimes are called the same but do not mean the same thing. Watch out.

Message statuses in medic-gateway


Message states in medic

scheduledNot yet due. Messages as part of a configured schedule start in this state and are changed to pending when due.
pendingDue to be sent. The SMS gateway should pick this up for sending. Auto replies and instant messages start in this state.
forwarded-to-gatewayMessage has been sent to gateway.
received-by-gatewayHas been received by the gateway.
forwarded-by-gatewayGateway has tried sending the message.
sentSuccessfully delivered to the sms network.
deliveredSuccessfully received by the recipient’s device.
failedThe sending attempt failed. Sending will not be retried without user intervention.
deniedThis will not be sent. The recipient phone number is configured to be denied via outgoing_deny_list, outgoing_deny_with_alphas, or outgoing_deny_shorter_than.
clearedThis will not be sent as a report has triggered an event to stop it. This can happen if a patient visit has occurred before the visit reminder is sent.
mutedThis will not be sent as the task has been deliberately stopped. Messages in this state can be unmuted by user action.

Timeline of the medic-gateway protocol for webapp-originating message

Read the table below like a vertical timeline : each time an event happens, the states/statuses corresponding to the message get updated.

Note 1 : Gateway only sends a status update for a message only if the “needs forwarding” flag for the message status is true, and then sets it back to false. So it only sends status updates once.

Note 2 : If api sends the same WO message again, then gateway sets its needs forwarding flag to true, and so sends the status at the next poll.

Note 3 : not all of the events below happen every time : this is assuming only one step of SMS-sending happens between each poll. If several steps happened, then some of the events below are skipped. If several status changes have happened between polls, Gateway will report the multiple new statuses at the next poll.

numberEventwebapp stategateway statusgateway “Needs forwarding” flag
1Due date to send the message passespending
2Gateway polls and gets a new WO messageforwarded-to-gateway
3Gateway saves message in its DBforwarded-to-gatewayUNSENTtrue
4Gateway reports UNSENT status for the messagereceived-by-gatewayUNSENTfalse
5Gateway sends the messagereceived-by-gatewayPENDINGtrue
6Gateway reports PENDING status for the messageforwarded-by-gatewayPENDINGfalse
7Gateway gets confirmation the message leftforwarded-by-gatewaySENTtrue
8Gateway reports SENT status for the messagesentSENTfalse
9Gateway gets confirmation the message arrivedsentDELIVEREDtrue
10Gateway reports DELIVERED status for the messagedeliveredDELIVEREDfalse

CHT Applications > Features > Messaging

Messaging for Care Coordination, Alerts, and Notifications

CHT Applications > Quick Guides > Messaging > Message Loops

How to avoid messaging loops

CHT Applications > Reference > app_settings.json > .sms

SMS Settings: Instructions and schema for defining SMS settings