Skip to main content

RainMaker Push Notification Payloads

Follow these steps to configure and enable push notifications.

Notification Schemas​

Android​

Amazon SNS supports Firebase Cloud Messaging (FCM) to send notifications to Android application users. Google Cloud Messaging (GCM) is a depreciated version of it. Amazon SNS uses FCM under the hood for both FCM and GCM platforms.

Starting July 22, 2024, Google has discontinued support for mobile push notifications via the legacy FCM APIs. RainMaker now uses the new FCM HTTP v1 API format.

Note: Despite the change in the message format, the mobile application receives only the "data" key of the android notification payload which is same as before.

Unescaped payload sent by the Rainmaker (Old format):

{
  "GCM": "{
    "data": {
      "title": "ESP RainMaker",
      "body": "",
      "event_data_payload": {
        "event_version": "v1",
        "id": "1",
        "event_type": "rmaker.event.<event_type>",
        "timestamp": 1648563678737,
        "description": "",
        "event_data": {}
      }
    }
  }"
}

Unescaped payload sent by the Rainmaker (New format):

{
  "GCM": "{
    "fcmV1Message": {
      "message": {
        "data": {
          "title": "ESP RainMaker",
          "body": "",
          "event_data_payload": "{
             "event_version": "v1",
             "id": "1",
             "event_type": "rmaker.event.<event_type>",
             "timestamp": 1648563678737,
             "description": "",
             "event_data": {}
          }"
        }
      }
    }
  }"
}

The Unescaped JSON event details received by the phone apps are of format:

{
	"data": {
		"title": "ESP RainMaker",
		"body": "",
		"event_data_payload": "{
			"event_version": "v1",
			"id": "1",
			"event_type": "rmaker.event.<event_type>",
			"timestamp": 1648563678737,
			"description": "",
			"event_data": {}
		}"
	}
}

The phone apps gets only the "data" key-value part and it remains the same for both legacy and FCMv1 formats. You can modify the payload of notifications if required.


iOS​

Amazon SNS supports Apple Push Notification service to send notifications to iOS application users. You can use the APNs sandbox channel to send push notification messages to the sandbox environment of the Apple Push Notification service (APNs) for pre-production testing.

The payload that RainMaker sends is of format:

{
    "APNS/APNS_SANDBOX": "Escaped JSON event details with iOS supported attributes"
}

The Escaped JSON event details received by the phone apps are of format:

{
	"aps": {
		"alert": {
			"title": "ESP RainMaker",
			"body": "",
			"event_data_payload": {
				"event_version": "v1",
				"id": "1",
				"event_type": "rmaker.event.<event_type>",
				"timestamp": 1648563678737,
				"description": "",
				"event_data": {}
			}
		},
		"mutable-content": 1
	}
}

You can mutate the payload of notifications if required. Reference

A sound key with default value is added to the current iOS payload for all events except node params change, to trigger notification with default sound.

Notification Payloads​

Note: The event-wise payloads given below are unescaped at all levels for readability. Actual payloads received are escaped valid json payloads. Below is an example of actual escaped payload for an event, ex: Node Alerts.

AndroidiOS
{"GCM": "{\"fcmV1Message\":{\"message\":{\"data\":{\"title\":\"ESP RainMaker\",\"body\":\"Alert received from a node\",\"event_data_payload\":\"{\\\"event_version\\\":\\\"v1\\\",\\\"id\\\":\\\"1\\\",\\\"event_type\\\":\\\"rmaker.event.alert\\\",\\\"timestamp\\\":1648706009358,\\\"description\\\":\\\"Alert received from a node\\\",\\\"event_data\\\":{\\\"message_body\\\":\\\"{\\\\\\"Alert\\\\\\":\\\\\\"Sample alert\\\\\\"}\\\",\\\"node_id\\\":\\\"EPRoUZemZPDiHjKrHoD74f\\\"}}\"}}}}"}{ "APNS": "{\"aps\":{\"alert\":{\"title\":\"ESP RainMaker\",\"body\":\"Alert received from a node\",\"event_data_payload\":{\"event_version\":\"v1\",\"id\":\"1\",\"event_type\":\"rmaker.event.alert\",\"timestamp\":1648706009358,\"description\":\"Alert received from a node\",\"event_data\":{\"message_body\":\"{\\\"Alert\\\":\\\"Sample alert\\\"}\",\"node_id\":"\EPRoUZemZPDiHjKrHoD74f\"}}},\"mutable-content\":1,\"sound\":\"default\"}}"}

Refer the below unescaped payload examples for event-specific notification payloads:


1. Node Connected​

Android:

{
  "data": {
    "title": "ESP RainMaker",
    "body": "Node(s) connected to cloud",
    "event_data_payload": "{
      "event_version": "v1",
      "id": "1",
      "event_type": "rmaker.event.node_connected",
      "timestamp": 1648563678737,
      "description": "Node(s) connected to cloud",
      "event_data": {
        "user_id": "1fd342a3-7531-48a0-9d97-4242a8502ed4",
        "node_id": "EPRoUZemZPDiHjKrHoD74f",
        "connectivity": {
          "connected": true,
          "timestamp": 1648563678517
        }
      }
    }"
  }
}

iOS:

{
  "aps": {
    "alert": {
      "title": "ESP RainMaker",
      "body": "Node(s) connected to cloud",
      "event_data_payload": {
        "event_version": "v1",
        "id": "1",
        "event_type": "rmaker.event.node_connected",
        "timestamp": 1648563678737,
        "description": "Node(s) connected to cloud",
        "event_data": {
          "user_id": "1fd342a3-7531-48a0-9d97-4242a8502ed4",
          "node_id": "EPRoUZemZPDiHjKrHoD74f",
          "connectivity": {
            "connected": true,
            "timestamp": 1648563678517
          }
        }
      }
    },
    "mutable-content": 1,
    "sound": "default"
  }
}

2. Node Disconnected​

Android:

{
  "data": {
    "title": "ESP RainMaker",
    "body": "Node(s) disconnected from cloud",
    "event_data_payload": "{
      "event_version": "v1",
      "id": "1",
      "event_type": "rmaker.event.node_disconnected",
      "timestamp": 1648563564021,
      "description": "Node(s) disconnected from cloud",
      "event_data": {
        "user_id": "1fd342a3-7531-48a0-9d97-4242a8502ed4",
        "node_id": "EPRoUZemZPDiHjKrHoD74f",
        "connectivity": {
          "connected": false,
          "timestamp": 1648563558181
        }
      }
    }"
  }
}

iOS:

{
  "aps": {
    "alert": {
      "title": "ESP RainMaker",
      "body": "Node(s) disconnected from cloud",
      "event_data_payload": {
        "event_version": "v1",
        "id": "1",
        "event_type": "rmaker.event.node_disconnected",
        "timestamp": 1648563564021,
        "description": "Node(s) disconnected from cloud",
        "event_data": {
          "user_id": "1fd342a3-7531-48a0-9d97-4242a8502ed4",
          "node_id": "EPRoUZemZPDiHjKrHoD74f",
          "connectivity": {
            "connected": false,
            "timestamp": 1648563558181
          }
        }
      }
    },
    "mutable-content": 1,
    "sound": "default"
  }
}

3. Node Params change​

Android:

{
  "data": {
    "title": "ESP RainMaker",
    "body": "Node parameters updated",
    "event_data_payload": "{
      "event_version": "v1",
      "id": "1",
      "event_type": "rmaker.event.node_params_changed",
      "timestamp": 1648563339270,
      "description": "Node parameters updated",
      "event_data": {
        "user_id": "1fd342a3-7531-48a0-9d97-4242a8502ed4",
        "node_id": "EPRoUZemZPDiHjKrHoD74f",
        "payload": "{
          "Lightbulb": {
            "brightness": 75
          }
        }"
      }
    }"
  }
}

iOS:

{
  "aps": {
    "content-available": 1
  },
  "data": {
    "title": "ESP RainMaker",
    "body": "Node parameters updated",
    "event_data_payload": {
      "event_version": "v1",
      "id": "1",
      "event_type": "rmaker.event.node_params_changed",
      "timestamp": 1648563339270,
      "description": "Node parameters updated",
      "event_data": {
        "user_id": "1fd342a3-7531-48a0-9d97-4242a8502ed4",
        "node_id": "EPRoUZemZPDiHjKrHoD74f",
        "payload": "{
          "Lightbulb": {
            "brightness": 75
          }
        }"
      }
    }
  }
}

4. User Node Added​

Android:

{
  "data": {
    "title": "ESP RainMaker",
    "body": "New Node(s) added",
    "event_data_payload": "{
      "event_version": "v1",
      "id": "1",
      "event_type": "rmaker.event.user_node_added",
      "timestamp": 1648562696803,
      "description": "New Node(s) added",
      "event_data": {
        "user_id": "69304cb1-7572-4981-87d8-eb06681ca699",
        "user_role": "primary",
        "nodes": ["WXXuKyL4HBTFbBQvxfCa6j"]
      }
    }"
  }
}

iOS:

{
  "aps": {
    "alert": {
      "title": "ESP RainMaker",
      "body": "New Node(s) added",
      "event_data_payload": {
        "event_version": "v1",
        "id": "1",
        "event_type": "rmaker.event.user_node_added",
        "timestamp": 1648562696803,
        "description": "New Node(s) added",
        "event_data": {
          "user_id": "69304cb1-7572-4981-87d8-eb06681ca699",
          "user_role": "primary",
          "nodes": ["WXXuKyL4HBTFbBQvxfCa6j"]
        }
      }
    },
    "mutable-content": 1,
    "sound": "default"
  }
}

5. User Node Removed​

Android:

{
  "data": {
    "title": "ESP RainMaker",
    "body": "Node(s) removed",
    "event_data_payload": "{
      "event_version": "v1",
      "id": "1",
      "event_type": "rmaker.event.user_node_removed",
      "timestamp": 1648563123598,
      "description": "Node(s) removed by primary user",
      "event_data": {
        "user_id": "69304cb1-7572-4981-87d8-eb06681ca699",
        "user_role": "",
        "nodes": ["WXXuKyL4HBTFbBQvxfCa6j"]
      }
    }"
  }
}

iOS:

{
  "aps": {
    "alert": {
      "title": "ESP RainMaker",
      "body": "Node(s) removed",
      "event_data_payload": {
        "event_version": "v1",
        "id": "1",
        "event_type": "rmaker.event.user_node_removed",
        "timestamp": 1648563123598,
        "description": "Node(s) removed by primary user",
        "event_data": {
          "user_id": "69304cb1-7572-4981-87d8-eb06681ca699",
          "user_role": "",
          "nodes": ["WXXuKyL4HBTFbBQvxfCa6j"]
        }
      }
    },
    "mutable-content": 1,
    "sound": "default"
  }
}

6. Node Alerts​

Android:

{
  "data": {
    "title": "ESP RainMaker",
    "body": "Alert received from a node",
    "event_data_payload": "{
      "event_version": "v1",
      "id": "1",
      "event_type": "rmaker.event.alert",
      "timestamp": 1648706009358,
      "description": "Alert received from a node",
      "event_data": {
        "message_body": "{
          "Alert": "Sample alert"
        }",
        "node_id": "EPRoUZemZPDiHjKrHoD74f"
      }
    }"
  }
}

iOS:

{
  "aps": {
    "alert": {
      "title": "ESP RainMaker",
      "body": "Alert received from a node",
      "event_data_payload": {
        "event_version": "v1",
        "id": "1",
        "event_type": "rmaker.event.alert",
        "timestamp": 1648706009358,
        "description": "Alert received from a node",
        "event_data": {
          "message_body": "{
            "Alert": "Sample alert"
          }",
          "node_id": "EPRoUZemZPDiHjKrHoD74f"
        }
      }
    },
    "mutable-content": 1,
    "sound": "default"
  }
}

7. Node Automation Triggered​

Android:

{
  "data": {
    "title": "ESP RainMaker",
    "body": "Successfully triggered automation for some device(s)",
    "event_data_payload": "{
      "event_version": "v1",
      "id": "1",
      "event_type": "rmaker.event.node_automation_trigger",
      "timestamp": 1648560446262,
      "description": "Automation Triggered",
      "event_data": {
        "user_id": "1fd342a3-7531-48a0-9d97-4242a8502ed4",
        "automation_id": "a5rYFynf6XNjsNRJmarkbZ",
        "automation_name": "TurnOffWhen100",
        "node_id": "EPRoUZemZPDiHjKrHoD74f",
        "events": [{
          "params": {
            "Lightbulb": {
              "brightness": 100
            }
          },
          "check": "=="
        }],
        "actions": [{
          "node_id": "EPRoUZemZPDiHjKrHoD74f",
          "params": {
            "Lightbulb": {
              "power": false
            }
          }
        }],
        "status": [{
          "node_id": "EPRoUZemZPDiHjKrHoD74f",
          "status": "success",
          "description": "Node automation triggered"
        }]
      }
    }"
  }
}

iOS:

{
  "aps": {
    "alert": {
      "title": "ESP RainMaker",
      "body": "Successfully triggered automation for some device(s)",
      "event_data_payload": {
        "event_version": "v1",
        "id": "1",
        "event_type": "rmaker.event.node_automation_trigger",
        "timestamp": 1648560446262,
        "description": "Automation Triggered",
        "event_data": {
          "user_id": "1fd342a3-7531-48a0-9d97-4242a8502ed4",
          "automation_id": "a5rYFynf6XNjsNRJmarkbZ",
          "automation_name": "TurnOffWhen100",
          "node_id": "EPRoUZemZPDiHjKrHoD74f",
          "events": [{
            "params": {
              "Lightbulb": {
                "brightness": 100
              }
            },
            "check": "=="
          }],
          "actions": [{
            "node_id": "EPRoUZemZPDiHjKrHoD74f",
            "params": {
              "Lightbulb": {
                "power": false
              }
            }
          }],
          "status": [{
            "node_id": "EPRoUZemZPDiHjKrHoD74f",
            "status": "success",
            "description": "Node automation triggered"
          }]
        }
      }
    },
    "mutable-content": 1,
    "sound": "default"
  }
}

8. Node Shared with User​

Scenario: user1 sends a node sharing request to user2

Android (user2 receives sharing request):

{
  "data": {
    "title": "ESP RainMaker",
    "body": "New node sharing request received. Please accept or decline",
    "event_data_payload": "{
      "event_version": "v1",
      "id": "1",
      "event_type": "rmaker.event.user_node_sharing_add",
      "timestamp": 1648637838355,
      "description": "New node sharing request received. Please accept or decline",
      "event_data": {
        "user_id": "69304cb1-7572-4981-87d8-eb06681ca699",
        "nodes": ["WXXuKyL4HBTFbBQvxfCa6j"],
        "primary_user_name": "username2@domain.com",
        "request_id": "JBYejyPW3fx6uBBFnU3bsg",
        "metadata": {
          "devices": [{
            "name": "AC Switch",
            "type": "esp.device.switch"
          }]
        }
      }
    }"
  }
}

iOS (user2 receives sharing request):

{
  "aps": {
    "alert": {
      "title": "ESP RainMaker",
      "body": "New node sharing request received. Please accept or decline",
      "event_data_payload": {
        "event_version": "v1",
        "id": "1",
        "event_type": "rmaker.event.user_node_sharing_add",
        "timestamp": 1648637838355,
        "description": "New node sharing request received. Please accept or decline",
        "event_data": {
          "user_id": "69304cb1-7572-4981-87d8-eb06681ca699",
          "nodes": ["WXXuKyL4HBTFbBQvxfCa6j"],
          "primary_user_name": "username2@domain.com",
          "request_id": "JBYejyPW3fx6uBBFnU3bsg",
          "metadata": {
            "devices": [{
              "name": "AC Switch",
              "type": "esp.device.switch"
            }]
          }
        }
      }
    },
    "mutable-content": 1,
    "category": "ADD_SHARING",
    "sound": "default"
  }
}

On this page