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.