1.54 Program Messages

Program message lets you send messages to tracked entity instances, contact addresses associated with organisation units, phone numbers and email addresses. You can send messages through the messages resource.


1.54.1 Sending program messages

Program messages can be sent using two delivery channels:

  • SMS (SMS)

  • Email address (EMAIL)

Program messages can be sent to various recipients:

  • Tracked entity instance: The system will look up attributes of value type PHONE_NUMBER or EMAIL (depending on the specified delivery channels) and use the corresponding attribute values.

  • Organisation unit: The system will use the phone number or email information registered for the organisation unit.

  • List of phone numbers: The system will use the explicitly defined phone numbers.

  • List of email addresses: The system will use the explicitly defined email addresses.

Below is a sample JSON payload for sending messages using POST requests. Note that message resource accepts a wrapper object named programMessages which can contain any number of program messages.

POST /api/26/messages

    "programMessages": [{
        "recipients": {
            "trackedEntityInstance": {
                "id": "UN810PwyVYO"
            "organisationUnit": {
                "id": "Rp268JB6Ne4"
            "phoneNumbers": [
            "emailAddresses": [
        "programInstance": {
            "id": "f3rg8gFag8j"
        "programStageInstance": {
            "id": "pSllsjpfLH2"
        "deliveryChannels": [
            "SMS", "EMAIL"
        "subject": "Outbreak alert",
        "text": "An outbreak has been detected",
        "storeCopy": false

The fields are explained in the following table.

Program message payload
Field Required Description Values
recipients Yes Recipients of the program message. At least one recipient must be specified. Any number of recipients / types can be specified for a message. Can be trackedEntityInstance, organisationUnit, an array of phoneNumbers or an array of emailAddresses.
programInstance Either this or programStageInstance required The program instance / enrollment. Enrollment ID.
programStageInstance Either this or programInstance required The program stage instance / event. Event ID.
deliveryChannels Yes Array of delivery channels. SMS | EMAIL
subject No The message subject. Not applicable for SMS delivery channel. Text.
text Yes The message text. Text.
storeCopy No Whether to store a copy of the program message in DHIS2. false (default) | true

A minimalistic example for sending a message over SMS to a tracked entity instance looks like this:

curl -d @message.json "https://play.dhis2.org/demo/api/26/messages"
  -H "Content-Type:application/json" -u admin:district -v

    "programMessages": [{
        "recipients": {
            "trackedEntityInstance": {
                "id": "PQfMcpmXeFE"
        "programInstance": {
            "id": "JMgRZyeLWOo"
        "deliveryChannels": [
        "text": "Please make a visit on Thursday"

1.54.2 Retrieving and deleting program messages

The list of messages can be retrieved using GET.

GET /api/26/messages

One particular message can also be retrieved using GET.

GET /api/26/messages/{uid}

Message can be deleted using DELETE.

DELETE /api/26/messages/{uid}

1.54.3 Querying program messages

The program message API supports program message queries based on request parameters. Messages can be filtered based on below mentioned query parameters. All requests should use the GET HTTP verb for retrieving information.

Query program messages API
Parameter URL
programInstance /api/26/messages?programInstance=6yWDMa0LP7
programStageInstance /api/26/messages?programStageInstance=SllsjpfLH2
trackedEntityInstance /api/26/messages?trackedEntityInstance=xdfejpfLH2
organisationUnit /api/26/messages?ou=Sllsjdhoe3
processedDate /api/26/messages?processedDate=2016-02-01