Output Format

AWS Integration MQTT Topics

For AWS Integrations the messages will be forwarded to a dedicated AWS IoT Core MQTT topic for each event type.

Event TypeAWS IoT Core MQTT Topic
ERRORerror
GEOFENCEgeofence
LOCATIONlocation
LIFECYCLElifecycle
TELEMETRY_DATALWM2M & UDP protocol:
{iccid}/messages

CoAP protocol with provided query parameter t:
{iccid}/{query_parameter_t}

CoAP protocol without provided query parameter t:
{iccid}
TEST_MESSAGEintegration-status

Examples

TELEMETRY_DATA

{
  "payload": {
    "type": "JSON",
    "value": {
      "latitude": 7.490929188596135e+247,
      "longitude": 2.586343401687847e+161
    }
  },
  "received": "1670598749915",
  "id": "1-6393505d-67fa8489fb9c791fcddd43f0",
  "source": "UDP",
  "type": "TELEMETRY_DATA",
  "version": "1.0.0",
  "device": {
    "iccid": "8988280666000002864",
    "ip": "100.91.200.24",
    "imsi": "901405100002864"
  }
}

LIFECYCLE

{
  "lifecycle": {
    "type": "DEVICE_FIRST_TIME_REGISTERED",
    "message": "New Device successfully registered for the first time - 8988280666000002864"
  },
  "received": "1670830184814",
  "id": "1-6396d868-d00f68b911b75bc761768e9b",
  "type": "LIFECYCLE",
  "version": "1.0.0",
  "device": {
    "iccid": "8988280666000002864",
    "ip": "100.91.200.24",
    "imsi": "901405100002864"
  }
}

ERROR

{
  "id": "1-87654321-4fff5fb82c196babcd00008",
  "type": "ERROR",
  "received": "1649931594333",
  "device": {
    "iccid": "1234567890123456789",
    "imsi": "987654321098765",
    "ip": "127.0.0.1"
  },
  "error": {
    "id": "3dsd627637267sahdgyasd", 
    "type": "DEVICE",
    "message": "Translator[UserPayloadError]",
    "description": "Asset path:Temperature, Error: can't extract [200:201] from 2 bytes",
    "payloadExists": true
  },
  "version": "1.0.0"
}

GEOFENCE

{
  "id": "1-87654321-4fff5fb82c196babcd00007",
  "type": "GEOFENCE",
  "received": "1649931594333",
  "geofence": {
    "id": "Wg9ys5VqmSNN8M8YN2rv8",
    "name": "TEST_GEOFENCE_1",
    "coordinates": ["24.166234790073986","56.977086867785"],
    "type": "EXIT"
  },
  "device": {
    "ip": "100.91.200.20",
    "iccid": "1234567890123456789",
    "imsi": "987654321098765"
  },
  "version": "1.0.0"
}

LOCATION

{
  "id": "1-87654321-4fff5fb82c196babcd00007",
  "type": "LOCATION",
  "received": "1649931594333",
  "location": {
    "source": "CellTower",
    "coordinates": ["24.166234790073986","56.977086867785"],
    "metadata": {
      "verticalAccuracy": 45, 
      "verticalConfidenceLevel": 0.68, 
      "horizontalAccuracy": 303, 
      "horizontalConfidenceLevel": 0.68,
      "timestamp": "2022-11-18T12:23:58.189Z"
    }
  },
  "device": {
    "ip": "100.91.200.20",
    "iccid": "1234567890123456789",
    "imsi": "987654321098765"
  },
  "version": "1.0.0"
}

⚠️ Note that metadata parameter with accuracy data is only available in Advanced CellTower locator mode.

TEST_MESSAGE

This event can be triggered by Test AWS Integration or Test Webhook Integration endpoints. This event will be triggered also if an integration with status INTEGRATION_FAILED will be restarted.

{
  "id": "1-63d889d3-d987cbb90f8f10c76278d8dd",
  "type": "TEST_MESSAGE",
  "received": "1675135445411",
  "integration": {
    "id": "X8qB3FhJQyffUH0GqL3gC",
    "name": "integration-name"
   },
  "version": "1.0.0"
}

Message Properties

These are the properties of a message. It contains parameters that help to identify the message and the device that has sent the message.

PropertyData TypeDescriptionPresent in event types. *Optional
typeENUMSource event type.
Values: LIFECYCLE, TELEMETRY_DATA, ERROR, GEOFENCE, TEST_MESSAGE
All
receivedSTRINGUNIX Timestamp. Received message date and time in milliseconds since midnight, January 1, 1970 UTC.All
sourceENUMValues: UDP, COAP, LWM2MTELEMETRY_DATA
versionSTRINGVersion number of our Payload-Format. With new version, format can change.All
idSTRINGUnique ID for each message sent.All
deviceJSON ObjectObject describing device from which the message was received.TELEMETRY_DATA, GEOFENCE, LIFECYCLE, *ERROR, LOCATION
payloadJSON ObjectObject describing message payload.TELEMETRY_DATA
lifecycleJSON ObjectLifecycle object.LIFECYCLE
errorJSON ObjectObject describing error.ERROR
geofenceJSON ObjectObject describing geofence event.GEOFENCE
integrationJSON ObjectObject describing integration.TEST_MESSAGE
locationJSON ObjectObject describing location.LOCATION

Payload Properties

These are the properties of a message payload object. It contains message payload properties.

PropertyData TypeDescription
typeENUMValues: JSON, STRING
encodingENUMPresent only for UDP and COAP raw messages that hasn't been traversed through translation service.
Values: base64.
valuesee typePayload value.
topicSTRINGPresent only for COAP messages.

Device Properties

These are the properties of a message device object. It contains parameters that help to identify the device that has sent the message.

PropertyData TypeDescription
iccidSTRINGDevice iccid.
imsiSTRINGDevice imsi1.
ipSTRINGDevice ip address in 1nce network.

Lifecycle properties

These are the properties for lifecycle events and it is present only for lifecycle messages.

PropertyData TypeDescription
typeENUMValues: DEVICE_FIRST_TIME_REGISTERED
messageSTRINGDescription of lifecycle event

Error properties

These are the properties of a message error object. It is present only for error messages.

PropertyData TypeDescription
idSTRINGError id
typeENUMValues: DEVICE, GENERAL, INTEGRATION, LOCATION
messageSTRINGShort error message
descriptionSTRINGDetailed error description
payloadExistsBOOLEANDoes Error contains payload

Geofence properties

These are the properties of a message geofence object. It is present only for geofence messages.

PropertyData TypeDescription
idSTRINGGeofence id
typeENUMValues: EXIT, ENTER
nameSTRINGName of geofence
coordinatesSTRING ARRAYCoordinate of location which triggered the geofence event
[ longitude, latitude ]

Integration properties

These are the properties of a message integration object.

PropertyData TypeDescription
idSTRINGIntegration id
nameSTRINGName of integration

Location properties

These are the properties of a message location object. It is present only for location messages.

PropertyData TypeDescription
sourceENUMValues: GPS, CellTower
coordinatesSTRING ARRAYCoordinate of location which triggered the location event
[ longitude, latitude ]
metadataOBJECTOptional JSON field with position metadata like vertical accuracy, country, etc