Data router messages and topics

For a description of Routing Rules, see the guide.

More information can be found at the Data Message Guide

Limited access functionality
Routes functionality is limited to certain legacy accounts. For more information, please reach out to our sales team.

 

Data message fields

The Data Router sends these fields to downstream apps and webhook recipients by default. These fields are also available in templates for the Advanced Webhook Builder routing rule.

{
  "received": "2016-09-27T18:53:09.302915",
  "authtype": "psk",
  "tags": ["TOPIC1", "_DEVICE_12345_"],
  "device": {"id": 5678, "name": "My Device"},
  "errorcode": 0,
  "source": "abcd",
  "timestamp": "0",
  "data": "SGVsbG8sIHdvcmxkIQo="
}

• received — ISO8601-formatted UTC timestamp when the message was received by the Router
• tags — Array of topics that the message belongs to
• device.name — Human-readable name of the device, as specified in the Hologram Dashboard
• device.id — Integer ID of the device
• data — Base64-encoded representation of the data payload
• authtype — Method by which the message sender authenticated with the Data Engine
• errorcode — 0 for messages processed successfully
• source — Source ID from the Router credentials used to send the message. This corresponds to a specific Hologram device. Some data sources use a different authentication method so this field may not always be present.

System topics

The Router will automatically append certain topics based on the source and protocol of the message. All system topics begin and end with an underscore character, e.g. _SIMPLESTRING_. For security and consistency reasons, you are not able to specify these system topics explicitly.

Topic	Description
_API_RESP_	When a device responds to a message sent using the cloud-to-device API or Dashboard features, the response contains this topic
_DEVICE_XXX_	Messages relating to a specific device get assigned a topic containing the device ID, e.g._DEVICE_1234_.
_IMEI_FIRST_	Message indicates that we just saw the first IMEI assigned for the given device. More information will be in message body.
_IMEI_CHANGE_	Message indicates the the IMEI assigned to the device has changed. More information will be in message body.
_IMEI_TAC_CHANGE_	Comes along with_IMEI_CHANGE_and indicates that not only did the IMEI change but the first 8 digits changed, meaning that this is a new type of hardware.
_JSONSTRING_	Messages that come in via our socket API and use the JSON data format
_RESTAPI_	Messages that come in via our REST API (as opposed to our socket API)
_SOCKETAPI_	Messages that come in via our socket API (as opposed to HTTP REST API)
_SIMPLESTRING_	Messages that come in via our socket API and use the string data format
_SMS_	Messages that come in through our SMS-over-IP endpoint, or the Hologram SMS phone number
_SMS_DO_	Messages sent to the CSR via Hologram's SMS phone number will contain this topic.
_SMS_DT_	SMS messages sent through our systems to a device will contain this topic
_SMS_DT_DELIVERED_	This message indicates that an SMS that was sent to a device through our systems was marked as delivered by the network.
_SMSOVERIP_	Messages that come in through our SMS-over-IP endpoint. Note: SMS-over-IP is no longer supported and requests will receive an error from the Hologram Cloud endpoint. For device-originated outbound SMS, customers may continue to use circuit switched SMS with Hologram IoT SIMs.
_TAG_XXX_	If the given device has a tag at the time the message is sent, then this topic will be applied for each tag with the tag ID.
_DATALIMIT_	This messages indicates that a data overage limit was triggered for a device

Webhook formats

Custom Webhook URL Rule

Method: POST

Headers:

• Content-Type — application/x-www-form-urlencoded

Form fields:

• userid —Hologram user ID
• payload —JSON-formatted message object
• key —Optional webhook key as configured in routing rule
• properties —JSON-formatted routing rule configuration:
• url —URL that the webhook was sent to
• user_id —Hologram user ID
• key —Optional webhook key as configured in routing rule

Note that the payload and properties fields are JSON objects within a form-url encoded body, so you may need to explicitly decode the JSON even if your HTTP library decodes the top-level fields in the body.

 

Advanced Webhook builder rule

Method: POST

Headers:

• Content-Type — If Send JSON Content Type is configured: application/json. Otherwise Content-Type is omitted.

Body: Determined by configured payload template.

See the Routing Rules guide for information on configuring the payload template for Advanced Webhook Builder rules.