Triggers dictate what and when you will be notified of on your shipments. The sections below outline common fields and behaviors that can be found within triggers in addition to providing examples of the various data structures you may come across.

Thresholds

Some triggers will only notify when a sensor is above or below a specified threshold (e.g. temperature below 32F, humidity above 50%). Triggers types that end in Min or Max provide the ability to do this.

This behavior applies to the follow trigger types: BatteryPowerMin, HumidityMin, HumidityMax, TemperatureMin, TemperatureMax, ProbeTemperatureMin, and ProbeTemperatureMax.

Delaying Alert Triggers

Certain alert triggers provide the ability to trigger only once a condition has persisted for a certain amount of time. For example, you can choose to be alerted only once your shipment has been delayed at the shipFrom address for 2 hours or if the temperature rose above 33F for 30 consecutive minutes.

intervalDelay and intervalDelayUnit are used to set these delays. intervalDelayUnit can be set to minutes, hours, days, or weeks. intervalDelay can be set to any number, however, the maximum value when combined with the specified unit cannot exceed 2 weeks.

Please note, minutes is not supported for location based delay triggers (e.g. Arrival Delay, Departure Delay, Prolonged Stop).

Where Do You Want To Be Alerted

Sometimes you don't need to know about an alert. For example, you likely won't want to see a light alert if the shipment is still being loaded. Triggers let you specify which part of the shipment you would or would not like to be notified on by setting the following three fields to true or false.

isActiveAtOrigin: Only alert me if the alert is triggered at the shipFrom address
isActiveInTransit: Only alert me if the alert is triggered in transit
isActiveAtDestination: Only alert me if the alert is triggered at the shipTo address

A minimum of one of these fields must be set to true when adding a trigger to an alert preset.

Trigger Code Snippets

Temperature Triggers

//Valid Field Values
"temperatureTriggers": [
    {
        "triggerValue": 0,
        "triggerUnit": "C || F",
        "intervalDelay": 0,
        "intervalDelayUnit": "minutes || hours || days || weeks",
        "type": "TemperatureMax || TemperatureMin || ProbeTemperatureMax || ProbeTemperatureMin",
        "isActiveAtOrigin": false,
      	"isActiveInTransit": true,
        "isActiveAtDestination": false
    }
]

//Examples
"temperatureTriggers": [
    {
      	//Immediately alert when the temperature is greater than 0C
        "triggerValue": 0,
        "triggerUnit": "C",
        "interval": 0,
      	"intervalDelayUnit": "",
        "type": "TemperatureMax",
        "isActiveAtOrigin": false,
      	"isActiveInTransit": true,
        "isActiveAtDestination": false
    },
    {
        //Alert when the temperature is less than 30F after the issue persists for 1 hour
        "triggerValue": 30,
        "triggerUnit": "F",
        "interval": 1,
      	"intervalDelayUnit":"hours",
        "type": "TemperatureMin",
        "isActiveAtOrigin": false,
      	"isActiveInTransit": true,
        "isActiveAtDestination": false
    },
    {
      //Immediately alert when a probe temperature reading is greater than 0C
      "triggerValue": 0,
      "triggerUnit": "C",
      "interval": 0,
        "intervalDelayUnit": "",
      "type": "ProbeTemperatureMax",
      "isActiveAtOrigin": false,
        "isActiveInTransit": true,
      "isActiveAtDestination": false
  },
  {
      //Alert when a probe temperature reading is less than -10F after the issue persists for 1 hour
      "triggerValue": -10,
      "triggerUnit": "F",
      "interval": 1,
        "intervalDelayUnit":"hours",
      "type": "ProbeTemperatureMin",
      "isActiveAtOrigin": false,
        "isActiveInTransit": true,
      "isActiveAtDestination": false
  }
]

Arrive/Depart Triggers

//Valid Field Values
"arriveDepartTriggers": [
    {
        "alertOn": "Departure || Arrival",
        "type": "ShipmentArriveDepart",
        "isActiveAtOrigin": true,
        "isActiveInTransit": false,
        "isActiveAtDestination": true
    }
]

//Examples
"arriveDepartTriggers": [
    {
        //Immediately alert when the shipment has arrived at the shipTo address
        "alertOn": "Arrival",
        "type": "ShipmentArriveDepart",
        "isActiveAtOrigin": false,
        "isActiveInTransit": false,
        "isActiveAtDestination": true
    },
    {
        //Immediately alert when the shipment has left at the shipFrom address
        "alertOn": "Departure",
        "type": "ShipmentArriveDepart",
        "isActiveAtOrigin": true,
        "isActiveInTransit": false,
        "isActiveAtDestination": false
    }
]

Interval Triggers

//Valid Field Values
"intervalTriggers": [
    {
        "type": "ShipmentETA || ShipmentDepartDelay || ShipmentStopped || Connectivity",
        "intervalDelay": 2,
        "intervalDelayUnit": "minutes || hours || days || weeks",
        "isActiveAtOrigin": true,
        "isActiveInTransit": true,
        "isActiveAtDestination": true
    }
]

//Examples
"intervalTriggers": [
    {
        //Alert when the shipment is going to reach the shipTo address 5 hours late
        "type": "ShipmentETA",
        "interval": 5,
        "intervalDelayUnit": "hours",
        "isActiveAtOrigin": true,
        "isActiveInTransit": true,
        "isActiveAtDestination": false
    },
    {
        //Alert when the shipment has been at the shipFrom address 5 hours longer than expected
        "type": "ShipmentDepartDelay",
        "interval": 5,
        "intervalDelayUnit": "hours",
        "isActiveAtOrigin": true,
        "isActiveInTransit": true,
        "isActiveAtDestination": false
    },
    {
        //Alert when the shipment has been stopped for 12 hours
        "type": "ShipmentStopped",
        "interval": 12,
        "intervalDelayUnit": "hours",
        "isActiveAtOrigin": true,
        "isActiveInTransit": true,
        "isActiveAtDestination": false
    },
    {
        //Alert when the Tive sensor has lost connectivity for 45 minutes
        "type": "Connectivity",
        "interval": 45,
        "intervalDelayUnit": "minutes",
        "isActiveAtOrigin": true,
        "isActiveInTransit": true,
        "isActiveAtDestination": true
    }
]

Shipment Inbound Triggers

//Valid Field Values
"shipmentInboundTriggers": [
    {
        "type": "ShipmentInbound",
        "triggerValue": "2",
        "triggerUnit": "Miles || Kilometers",
        "isActiveAtOrigin": true,
      	"isActiveInTransit": true,
        "isActiveAtDestination": true
    }
]

//Examples
"shipmentInboundTriggers": [
    {
        //Alert when the Tive sensor gets close to the destination
        "type": "ShipmentInbound",
        "triggerValue": "2",
        "triggerUnit": "Miles",
        "isActiveAtOrigin": true,
        "isActiveInTransit": true,
        "isActiveAtDestination": true
    }
]

Shock/Light Triggers

//Valid Field Values
"shockLightTriggers": [
    {
        "type": "ShockEvents || LightChanges",
        "isActiveAtOrigin": false,
      	"isActiveInTransit": true,
        "isActiveAtDestination": false
    }
]

//Examples
"shockLightTriggers": [
    {
        //Alert when the Tive sensor has detected a shock event
        "type": "ShockEvents",
        "isActiveAtOrigin": true,
        "isActiveInTransit": true,
        "isActiveAtDestination": true
    },
    {
        //Alert when the Tive sensor has detected light
        "type": "LightChanges",
        "isActiveAtOrigin": false,
        "isActiveInTransit": true,
        "isActiveAtDestination": false
    }
]

Percent Triggers

//Valid Field Values
"percentTriggers": [
    {
        "triggerValue": 25,
        "triggerUnit": "%",
        "type": "BatteryPowerMin || HumidityMin || HumidityMax",
        "isActiveAtOrigin": true,   
        "isActiveInTransit": true,
        "isActiveAtDestination": true
    }
]

//Examples
"percentTriggers": [
    {
        //Alert when the Tive tracker battery goes below 25%
        "triggerValue": 25,
        "triggerUnit": "%",
        "type": "BatteryPowerMin",
        "isActiveAtOrigin": true,
        "isActiveInTransit": true,
        "isActiveAtDestination": true
    },
    {
        //Alert when the humidty is less than 30%
        "triggerValue": 30,
        "triggerUnit": "%",
        "type": "HumidityMin",
        "isActiveAtOrigin": false,
        "isActiveInTransit": true,
        "isActiveAtDestination": false
    },
    {
        //Alert when the humidity is greater than 35%
        "triggerValue": 35,
        "triggerUnit": "%",
        "type": "HumidityMax",
        "isActiveAtOrigin": false,
      	"isActiveInTransit": true,
        "isActiveAtDestination": false
    }
]

Geofence Triggers

Please note: our public API only supports simple radius geofence triggers. To create geofences with custom shapes, please visit the Tive Platform.

//Valid Field Values
"geofenceTriggers": [
    {
        "locationId": 0,
        "alertOn": "Inside || Outside",
        "type": "LocationPerimeter",
        "isActiveAtOrigin": true,   
        "isActiveInTransit": true,
        "isActiveAtDestination": true
    }
]

//Examples
"geofenceTriggers": [
    {
        //Immediately alert when the shipment has entered the saved location's radius
        "locationId": 0,
        "alertOn": "Inside",
        "type": "LocationPerimeter",
        "isActiveAtOrigin": true,
        "isActiveInTransit": true,
        "isActiveAtDestination": true
    },
    {
        //Immediately alert when the shipment has entered the saved location's radius
        "locationId": 0,
        "alertOn": "Inside",
        "type": "LocationPerimeter",
        "isActiveAtOrigin": true,
        "isActiveInTransit": true,
        "isActiveAtDestination": true
    }
]

Route Deviation

Not currently supported via the public API. To create route deviation alert presets, please visit the Tive Platform.

All Trigger Types

The list above lists all trigger types which may be created via the API. When querying the API you may see other trigger types which include triggers that cannot be created via the API:

BatteryPowerMax
BatteryPowerMin
Connectivity
HumidityMax
HumidityMin
LightChanges
LocationPerimeter
PolygonGeofence
PressureMax
PressureMin
ProbeTemperatureMax
ProbeTemperatureMin
RedZoneGeofence
RiskZoneGeofence
RouteGeofence
ShipmentArriveDepart
ShipmentDepartDelay
ShipmentETA
ShipmentInbound
ShipmentStopped
ShockEvents
TemperatureMax
TemperatureMin

We're constantly improving the platform which may include adding new trigger types. If you're building logic dependent on this list be sure to include reasonable default behavior for unknown or unexpected values.