Triggers are used to create notifications that alert you when a specific event occurs (e.g. a change in temperature or a drop in volume). Triggers are defined at the Device or Distribution level and support conditions based on one or more Streams.
The Triggers API allows you to interact with your triggers (including creating new triggers, updating triggers, testing triggers, etc.).
All methods described in this page require Master API keys in the X-M2X-KEY header. For managing device triggers, device level API keys are also supported. Device level API keys can only access the Device which they belong to. Any attempt to use a Device level API key to access a different Device would result in a 403 Forbidden response. Learn more about API Keys.
When the conditions for a trigger have been met, a notification is delivered via POST request to the specified callback_url.
{
"event": "fired",
"device": { "id": "e534850ff4fc3c8bab86ac14b41d26f7", "name": "Test Device", "serial": "ABC123" },
"trigger": "High Temperature",
"conditions": {
"temperature": { "gt": 30, "reset": 28 }
},
"values": {
"temperature": { "value": 35, "timestamp": "2014-06-27T22:22:58.104Z", "unit": "ºC" }
},
"timeframe": 300,
"custom_data": "ABC",
"timestamp": "2014-06-27T22:22:58.104Z",
"location": {
"name": "Machines room",
"latitude": 40.77177,
"longitude": -73.97352,
"elevation": 0,
"timestamp": "2014-06-27T22:22:57.040Z"
}
}
GET /devices/{device_id}/triggers
GET /distributions/{distribution_id}/triggers
Retrieve list of triggers associated with the specified device or distribution.
200 OK
Content-Type: application/json
{ "triggers": [
{ "id": "1234",
"name": "high-temperature-and-humidity",
"conditions": {
"temperature": { "gt": 30, "reset": 28 },
"humidity": { "gte": 80, "lte": 90 }
},
"frequency": "single",
"timeframe": 300,
"callback_url": "http://example.com",
"url": "https://api-m2x.att.com/v2/devices/a4f919d931c265ddd7b76649eac22f7e/triggers/1234",
"status": "enabled",
"activated": true,
"send_location": true,
"notify_on_reset": false,
"custom_data": "Custom Data",
"payload_version": 2,
"created": "2014-09-09T19:15:00.353Z",
"updated": "2014-09-10T19:15:00.342Z" },
{ "id": "1235",
"name": "low-temperature-and-humidity",
"conditions": {
"temperature": { "lt": 5 },
"humidity": { "lte": 60 }
},
"frequency": "continuous",
"timeframe": 0,
"callback_url": "http://example.com",
"url": "https://api-m2x.att.com/v2/devices/a4f919d931c265ddd7b76649eac22f7e/triggers/1235",
"status": "enabled",
"activated": false,
"send_location": false,
"notify_on_reset": true,
"custom_data": "{ \"foo\": \"bar\" }",
"payload_version": 2,
"created": "2014-09-09T19:15:00.875Z",
"updated": "2014-09-10T19:15:00.823Z" } ] }
404 Not Found
Content-Type: application/json
{ "message": "Device Not Found", "description": "The resource you requested could not be found. Please verify that the correct resource path was provided, or refer to https://m2x.att.com/developer/documentation for complete API documentation." }
A developer will receive this response when the specified device does not exist or belongs to another developer.
404 Not Found
Content-Type: application/json
{ "message": "Distribution Not Found", "description": "The resource you requested could not be found. Please verify that the correct resource path was provided, or refer to https://m2x.att.com/developer/documentation for complete API documentation." }
A developer will receive this response when the specified distribution does not exist or belongs to another developer.
POST /devices/{device_id}/triggers
POST /distributions/{distribution_id}/triggers
Create a new trigger associated with the specified device or distribution. Accepts the following parameters:
name (required) the name of the new trigger.conditions (required) the condition(s) that must be met in order for the trigger to fire. For each stream listed in conditions an optional reset threshold can be defined. After a trigger is initially fired it will not be turned off again until at least one stream listed in conditions logs a value equal to or surpassing its respective reset threshold and thereafter logs a value meeting the respective condition. If a reset threshold is not specified, the condition's threshold value is used by default. Notice that the reset threshold is not supported by the eq, not or changed operators nor a combination of operators (e.g. combining gte and lte in a single stream).timeframe (optional) the number of seconds representing the largest interval that will be considered when evaluating values and conditions from different streams. The largest possible timeframe that can be set is 86,400 (24 hours). This attribute is only valid for multi-stream triggers.callback_url (required) the trigger payload is delivered to this callback URL through an HTTP POST request.frequency (required) either "single", "periodic" or "continuous".interval (conditionally required) the interval (in seconds) during which trigger notifications will be delivered, if and only if the trigger conditions continue to be met. Any datapoint received that falls outside of the trigger conditions will reset the trigger. This parameter is required if frequency is periodic. Should be an integer value between 1 and 86,400 (24 hours).status (optional) either "enabled" or "disabled. If omitted, defaults to "enabled".send_location (optional) either "true" or "false", indicating if the last known location of the device should be included in the payload. If omitted, defaults to "true".notify_on_reset (optional) either "true" or "false", indicating if the trigger should send a notification to the callback_url whenever the trigger gets reset. If omitted, defaults to "false".custom_data (optional) a static string of up to 5,000 characters that will be included in the notification payload sent to the callback_url.The frequency with which a trigger's payload will be delivered to the callback_url can be specified using the frequency parameter. There are three frequency options available:
single triggers with single notification frequency only deliver the trigger payload to the callback_url once, when the first datapoint matching the trigger conditions is received. The trigger payload will not be delivered again until at least one datapoint is received which falls outside any of the trigger's defined conditions. The payload for triggers with a single notification frequency is guaranteed to be delivered at least once, though there are instances in which the payload is delivered more than once.periodic triggers with a periodic notification frequency deliver the trigger payload to the callback_url once the trigger conditions have been met, and at most once per interval if the condition(s) continue to be met. Any datapoint received that falls outside of the trigger conditions will reset the trigger.continuous triggers with continuous notification frequency deliver the trigger payload to the callback_url each time a new datapoint matching the trigger conditions is received.Currently, the following operators are supported for conditions:
gt: stream must log a value greater than the one specified. This operator is only supported for numeric streams.gte: stream must log a value equal to or greater than the one specified. This operator is only supported for numeric streams.lt: stream must log a value lesser than the one specified. This operator is only supported for numeric streams.lte: stream must log a value equal to or lesser than the one specified. This operator is only supported for numeric streams.eq: stream must log a value equal to the one specified.not: stream must log a value different from the one specified.changed: if true, stream must log a value different than the previous one. If false, stream must log a value equal to the previous one.Content-Type: application/json
{ "name": "High temperature",
"conditions": {
"temperature": { "gt": 30, "reset": 28 },
"humidity": { "changed": true }
},
"frequency": "continuous",
"timeframe": 300,
"callback_url": "http://example.com",
"status": "enabled",
"send_location": true,
"notify_on_reset": false,
"custom_data": "{ \"foo\": \"bar\" }" }
201 Created
Content-Type: application/json
Location: https://api-m2x.att.com/v2/devices/b1e8abbad65cb52b0d75eb2e63efa782/triggers/1236
{ "id": "1236",
"name": "High temperature",
"conditions": {
"temperature": { "gt": 30, "reset": 28 },
"humidity": { "changed": true }
},
"frequency": "continuous",
"timeframe": 300,
"callback_url": "http://example.com/",
"url": "https://api-m2x.att.com/v2/devices/b1e8abbad65cb52b0d75eb2e63efa782/triggers/1236",
"status": "enabled",
"activated": false,
"send_location": true,
"notify_on_reset": false,
"custom_data": "{ \"foo\": \"bar\" }",
"payload_version": 2,
"created": "2014-09-09T19:15:10.875Z",
"updated": "2014-09-09T19:15:10.875Z" }
404 Not Found
Content-Type: application/json
{ "message": "Device Not Found", "description": "The resource you requested could not be found. Please verify that the correct resource path was provided, or refer to https://m2x.att.com/developer/documentation for complete API documentation." }
A developer will receive this response when the specified device does not exist or belongs to another developer.
404 Not Found
Content-Type: application/json
{ "message": "Distribution Not Found", "description": "The resource you requested could not be found. Please verify that the correct resource path was provided, or refer to https://m2x.att.com/developer/documentation for complete API documentation." }
A developer will receive this response when the specified distribution does not exist or belongs to another developer.
422 Unprocessable Entity
Content-Type: application/json
{ "message": "Validation Failed",
"errors": { "conditions": ["not_present"] } }
A developer will receive this response if one or more of these validations fail:
name must be provided (not_present).conditions object with the conditions to meet for each stream must be provided (not_present).conditions object must be in the proper format: the streams must exist on the same device, they must be numeric, the operators must be one of "lt" (lesser than), "lte" (lesser than or equal to), "eq" (equal to), "not" (different from), "gt" (greater than), "gte" (greater than or equal to), and the values must be numeric (not_valid).timeframe, if present, must be a number (not_numeric) between 0 and 86,400 (not_valid). For single-stream triggers, this value can only be 0 or null if present.not_present) and must be a valid URL (not_valid).not_valid). If omitted, the trigger is enabled by default.not_valid).not_present), and must be a number (not_numeric) between 1 and 86,400 (not_valid).GET /devices/{device_id}/triggers/{id}
GET /distributions/{distribution_id}/triggers/{id}
Get details of a specific trigger associated with an existing device or distribution.
200 OK
Content-Type: application/json
{ "id": "1234",
"name": "high-temperature",
"conditions": {
"temperature": { "gt": 30, "reset": 28 },
"humidity": { "changed": true }
},
"frequency": "continuous",
"timeframe": 300,
"callback_url": "http://example.com",
"url": "https://api-m2x.att.com/v2/devices/a4f919d931c265ddd7b76649eac22f7e/triggers/1234",
"status": "enabled",
"activated": true,
"send_location": true,
"notify_on_reset": false,
"custom_data": "Custom Data",
"payload_version": 2,
"created": "2014-09-09T19:15:00.651Z",
"updated": "2014-09-10T19:15:00.352Z" }
404 Not Found
Content-Type: application/json
{ "message": "Device Not Found", "description": "The resource you requested could not be found. Please verify that the correct resource path was provided, or refer to https://m2x.att.com/developer/documentation for complete API documentation." }
A developer will receive this response when the specified device does not exist or belongs to another developer.
404 Not Found
Content-Type: application/json
{ "message": "Distribution Not Found", "description": "The resource you requested could not be found. Please verify that the correct resource path was provided, or refer to https://m2x.att.com/developer/documentation for complete API documentation." }
A developer will receive this response when the specified distribution does not exist or belongs to another developer.
404 Not Found
Content-Type: application/json
{ "message": "Trigger Not Found", "description": "The resource you requested could not be found. Please verify that the correct resource path was provided, or refer to https://m2x.att.com/developer/documentation for complete API documentation." }
A developer will receive this response when the specified trigger does not exist.
PUT /devices/{device_id}/triggers/{id}
PUT /distributions/{distribution_id}/triggers/{id}
Update an existing trigger associated with the specified device or distribution. Accepts the following parameters:
name the name of the new trigger.conditions the condition(s) that must be met in order for the trigger to fire. For each stream listed in conditions an optional reset threshold can be defined. After a trigger is initially fired it will not be turned off again until at least one stream listed in conditions logs a value equal to or surpassing its respective reset threshold and thereafter logs a value meeting the respective condition. If a reset threshold is not specified, the condition's threshold value is used by default. Notice that the reset threshold is not supported by the eq, not or changed operator nor a combination of operators (e.g. combining gte and lte in a single stream).timeframe the number of seconds representing the largest interval that will be considered when evaluating values and conditions from different streams. The largest possible timeframe that can be set is 86,400 (24 hours). This attribute is only valid for multi-stream triggers.callback_url the trigger payload is delivered to this callback URL through an HTTP POST request.frequency either "single", "periodic" or "continuous".interval (conditionally required) the interval (in seconds) during which trigger notifications will be delivered, if and only if the trigger conditions continue to be met. Any datapoint received that falls outside of the trigger conditions will reset the trigger. This parameter is required if frequency is periodic. Should be an integer value between 1 and 86,400 (24 hours).status either "enabled" or "disabled. If omitted, defaults to "enabled".send_location either "true" or "false", indicating if the last known location of the device should be included in the payload. If omitted, defaults to "true".notify_on_reset (optional) either "true" or "false", indicating if the trigger should send a notification to the callback_url whenever the trigger gets reset.custom_data (optional) a static string of up to 5,000 characters that will be included in the notification payload sent to the callback_url.The frequency with which a trigger's payload will be delivered to the callback_url can be specified using the frequency parameter. There are three frequency options available:
single triggers with single notification frequency only deliver the trigger payload to the callback_url once, when the first datapoint matching the trigger conditions is received. The trigger payload will not be delivered again until at least one datapoint is received which falls outside any of the trigger's defined conditions. The payload for triggers with a single notification frequency is guaranteed to be delivered at least once, though there are instances in which the payload is delivered more than once.periodic triggers with a periodic notification frequency deliver the trigger payload to the callback_url once the trigger conditions have been met, and at most once per interval if the condition(s) continue to be met. Any datapoint received that falls outside of the trigger conditions will reset the trigger.continuous triggers with continuous notification frequency deliver the trigger payload to the callback_url each time a new datapoint matching the trigger conditions is received.Currently, the following operators are supported for conditions:
gt: stream must log a value greater than the one specified. This operator is only supported for numeric streams.gte: stream must log a value equal to or greater than the one specified. This operator is only supported for numeric streams.lt: stream must log a value lesser than the one specified. This operator is only supported for numeric streams.lte: stream must log a value equal to or lesser than the one specified. This operator is only supported for numeric streams.eq: stream must log a value equal to the one specified.not: stream must log a value different from the one specified.changed: if true, stream must log a value different than the previous one. If false, stream must log a value equal to the previous one.Content-Type: application/json
{ "name": "High temperature",
"conditions": {
"temperature": { "gt": 30, "reset": 28 },
"humidity": { "changed": true }
},
"frequency": "continuous",
"timeframe": 300,
"callback_url": "http://example.com",
"status": "enabled",
"send_location": false,
"notify_on_reset": false,
"custom_data": "{ \"foo\": \"bar\" }" }
204 No Content
404 Not Found
Content-Type: application/json
{ "message": "Device Not Found", "description": "The resource you requested could not be found. Please verify that the correct resource path was provided, or refer to https://m2x.att.com/developer/documentation for complete API documentation." }
A developer will receive this response when the specified device does not exist or belongs to another developer.
404 Not Found
Content-Type: application/json
{ "message": "Distribution Not Found", "description": "The resource you requested could not be found. Please verify that the correct resource path was provided, or refer to https://m2x.att.com/developer/documentation for complete API documentation." }
A developer will receive this response when the specified distribution does not exist or belongs to another developer.
404 Not Found
Content-Type: application/json
{ "message": "Trigger Not Found", "description": "The resource you requested could not be found. Please verify that the correct resource path was provided, or refer to https://m2x.att.com/developer/documentation for complete API documentation." }
A developer will receive this response when the specified trigger does not exist.
422 Unprocessable Entity
Content-Type: application/json
{ "message": "Validation Failed",
"errors": { "conditions": ["not_present"] } }
A developer will receive this response if one or more of these validations fail:
not_present).not_present).not_valid).timeframe, if present, must be a number (not_numeric) between 0 and 86,400 (not_valid). For single-stream triggers, this value can only be 0 or null if present.not_present) and must be a valid URL (not_valid).not_valid).not_valid).not_present), and must be a number (not_numeric) between 1 and 86,400 (not_valid).POST /devices/{device_id}/triggers/{id}/test
POST /distributions/{distribution_id}/triggers/{id}/test
Test the specified trigger by firing it with fake values. This method can be used by developers of client applications to test the way their apps receive and handle M2X notifications.
The client applications should be prepared to receive a POST request with an application/json body containing the following elements:
device Device's info object containing id, name and serial attributes.trigger The trigger's name.conditions The conditions that caused the trigger to be fired.values The values that caused the trigger to be fired.timeframe The number of seconds representing the largest interval that will be considered when evaluating values and conditions from different streams.timestamp The timestamp at which the last value that caused the trigger to be fired was received.location The device's location at the moment the value has been pushed. (If send_location is true){
"event": "fired",
"device": { "id": "e534850ff4fc3c8bab86ac14b41d26f7", "name": "Test Device", "serial": "ABC123" },
"trigger": "High Temperature",
"conditions": {
"temperature": { "gt": 30, "reset": 28 }
},
"values": {
"temperature": { "value": 35, "timestamp": "2014-06-27T22:22:58.104Z", "unit_symbol": "ºC" }
},
"timeframe": 300,
"custom_data": "ABC",
"timestamp": "2014-06-27T22:22:58.104Z",
"location": {
"name": "Machines room",
"latitude": 40.77177,
"longitude": -73.97352,
"elevation": 0,
"timestamp": "2014-06-27T22:22:57.040Z"
}
}
200 OK
Content-Type: application/json
{ "trigger": {
"id": "1234",
"name": "high-temperature",
"conditions": {
"temperature": { "gt": 30, "reset": 28 }
},
"frequency": "continuous",
"timeframe": 300,
"callback_url": "http://example.com",
"url": "https://api-m2x.att.com/v2/devices/a4f919d931c265ddd7b76649eac22f7e/triggers/1234",
"status": "enabled",
"activated": false,
"send_location": true,
"notify_on_reset": false,
"custom_data": "Custom Data",
"payload_version": 2,
"created": "2014-09-09T19:15:00.353Z",
"updated": "2014-09-10T19:15:00.342Z"
},
"success": true,
"response": {
"body": "OK!",
"status": 200,
"headers": { "Content-Type": ["text/plain"] }
}
}
200 OK
Content-Type: application/json
{ "trigger": {
"id": "1234",
"name": "high-temperature",
"conditions": {
"temperature": { "gt": 30, "reset": 28 }
},
"frequency": "continuous",
"timeframe": 300,
"callback_url": "http://example.com",
"url": "https://api-m2x.att.com/v2/devices/a4f919d931c265ddd7b76649eac22f7e/triggers/1234",
"status": "enabled",
"activated": false,
"send_location": true,
"notify_on_reset": false,
"custom_data": "Custom Data",
"payload_version": 2,
"created": "2014-09-09T19:15:00.353Z",
"updated": "2014-09-10T19:15:00.342Z"
},
"success": false,
"error": "Could not resolve the callback URL."
}
404 Not Found
Content-Type: application/json
{ "message": "Device Not Found", "description": "The resource you requested could not be found. Please verify that the correct resource path was provided, or refer to https://m2x.att.com/developer/documentation for complete API documentation." }
A developer will receive this response when the specified device does not exist or belongs to another developer.
404 Not Found
Content-Type: application/json
{ "message": "Distribution Not Found", "description": "The resource you requested could not be found. Please verify that the correct resource path was provided, or refer to https://m2x.att.com/developer/documentation for complete API documentation." }
A developer will receive this response when the specified distribution does not exist or belongs to another developer.
404 Not Found
Content-Type: application/json
{ "message": "Trigger Not Found", "description": "The resource you requested could not be found. Please verify that the correct resource path was provided, or refer to https://m2x.att.com/developer/documentation for complete API documentation." }
A developer will receive this response when the specified trigger does not exist.
DELETE /devices/{device_id}/triggers/{id}
DELETE /distributions/{distribution_id}/triggers/{id}
Delete an existing trigger associated with a specific device or distribution.
Deleting a trigger does not remove any of it's past notifications from the Triggers Log.
204 No Content
404 Not Found
Content-Type: application/json
{ "message": "Device Not Found", "description": "The resource you requested could not be found. Please verify that the correct resource path was provided, or refer to https://m2x.att.com/developer/documentation for complete API documentation." }
A developer will receive this response when the specified device does not exist or belongs to another developer.
404 Not Found
Content-Type: application/json
{ "message": "Distribution Not Found", "description": "The resource you requested could not be found. Please verify that the correct resource path was provided, or refer to https://m2x.att.com/developer/documentation for complete API documentation." }
A developer will receive this response when the specified distribution does not exist or belongs to another developer.
404 Not Found
Content-Type: application/json
{ "message": "Trigger Not Found", "description": "The resource you requested could not be found. Please verify that the correct resource path was provided, or refer to https://m2x.att.com/developer/documentation for complete API documentation." }
A developer will receive this response when the specified trigger does not exist.
GET /devices/{device_id}/triggers/log
Retrieve the log of notifications sent by the triggers of the device. Each entry contains the payload sent by the trigger along with the response_code returned by the server that received the payload. If the callback_url was invalid or there was a network error, response_code will be 0 to indicate no response was received.
This endpoint returns the 100 most recent trigger notifications.
200 OK
Content-Type: application/json
{
"entries": [
{
"event": "fired",
"device": { "id": "e534850ff4fc3c8bab86ac14b41d26f7", "name": "Test Device", "serial": "ABC123" },
"trigger": "High Temperature",
"conditions": {
"temperature": { "gt": 30, "reset": 28 }
},
"values": {
"temperature": { "value": 35, "timestamp": "2014-06-27T22:22:58.104Z", "unit_symbol": "ºC" }
},
"timeframe": 300,
"custom_data": "ABC",
"timestamp": "2014-06-27T22:22:58.104Z",
"location": {
"name": "Machines room",
"latitude": 40.77177,
"longitude": -73.97352,
"elevation": 0,
"timestamp": "2014-06-27T22:22:57.040Z"
},
"response_code": 200
}
]
}
403 Forbidden
Content-Type: application/json
{ "message": "Account Not Active", "description": "Your account has not been activated yet. If you need to re-send the activation email, please visit https://m2x.att.com/activation-required" }
404 Not Found
Content-Type: application/json
{ "message": "Device Not Found", "description": "The resource you requested could not be found. Please verify that the correct resource path was provided, or refer to https://m2x.att.com/developer/documentation for complete API documentation." }
A developer will receive this response when the specified device does not exist or belongs to another developer.
404 Not Found
Content-Type: application/json
{ "message": "Distribution Not Found", "description": "The resource you requested could not be found. Please verify that the correct resource path was provided, or refer to https://m2x.att.com/developer/documentation for complete API documentation." }
A developer will receive this response when the specified distribution does not exist or belongs to another developer.
