Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.hologram.io/llms.txt

Use this file to discover all available pages before exploring further.

Limited access: Routes access is limited to certain legacy contracted organizations. If you are having issues with routes, please reach out to support.

​
Data message fields

Default fields sent to downstream apps and webhook recipients: 
{
  "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="
}

​
Field reference

  • received: ISO8601-formatted UTC timestamp when the message was received by the Data 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 device ID.
  • 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. Some data sources use a different authentication method so this field may not always be present.

​
System topics

The Router appends system topics based on source and protocol. System topics begin and end with underscores (for example, _SIMPLESTRING_) and cannot be specified by users.
TopicDescription
_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 (for example, _DEVICE_1234_).
_IMEI_FIRST_Indicates we just saw the first IMEI assigned for the given device. More information is in the message body.
_IMEI_CHANGE_Indicates the IMEI assigned to the device has changed. More information is in the message body.
_IMEI_TAC_CHANGE_Indicates the first 8 digits of the IMEI changed, meaning 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_Indicates that an SMS 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.
_TAG_XXX_If the given device has a tag at the time the message is sent, a topic is applied for each tag with the tag ID.
_DATALIMIT_Indicates that a data overage limit was triggered for a device.

​
Webhook formats

When creating a route, you can either use a basic webhook URL POST request or send an authenticated JSON payload to a webhook URL using the Advanced Webhook Builder.

​
Custom Webhook URL Rule

Method: POST Headers:
  • Content-Type: application/x-www-form-urlencoded
Form fields include:
  • userid: Hologram user ID
  • payload: JSON-formatted message object
  • key: Optional webhook key as configured in the routing rule
  • properties: JSON-formatted routing rule configuration (for example, url, user_id, key)
Note: The payload and properties fields are JSON objects within a form-urlencoded body, so you may need to explicitly decode the JSON even if your HTTP library decodes the top-level fields.

​
Advanced Webhook Builder rule

Method: POST Headers:
  • If configured to send JSON: Content-Type: application/json; otherwise omitted
Body is determined by the configured template.

Create and manage Routes (Legacy)