SMS Alerts Guide – Tech Mahindra’s Arrayent ConnectCloud IoT Platform Developers Portal

In this document you will find:

A conceptual overview of SMS alerts

A how-to guide on implementing SMS alerts

Overview

See Overview for an overview of alerts. The SMS Alerts feature of the Arrayent Cloud enables your customers to receive automated text messages when important events occur in their connected devices. For example, suppose that you manufacture a thermostat and want to enable your customers to receive SMS text messages when smoke is detected. First, you would modify the host application in your device to send a status update, say IsSmokeDetected =true, when it detects smoke. Next, you would modify your web or smartphone application to create an alert definition that is triggered when IsSmokeDetected == true. The remainder of this guide explains how to create, read, modify, and delete alert definitions using the Arrayent web service API.
Implementing SMS Alerts

Configuring the Cloud for SMS Alerts

Contact your Arrayent account manager to enable alerts on your Arrayent cloud environment. If you do not have an account manager or do not know who is your account manager, email sales@arrayent.com.
Implementing SMS Alerts with the Arrayent Web Service API
Creating SMS alerts with addTrigger

Use addTrigger to create SMS alerts. Below is the generic signature of an addTrigger request for SMS alerts specifically.
https://<SUBDOMAIN>.arrayent.com/zdk/services/zamapi/addTrigger?
secToken=<SECURITY TOKEN>&devId=<DEVICE ID>&action=sms&attrName=
<DEVICE ATTRIBUTE NAME>&operation={>|>=|<|<=|==|regex|equals}&
threshold=<THRESHOLD>&address=<PHONE NUMBER>&msg=<MESSAGE>&
autoDisarm={true|false}&autoDisable={true|false}&autoDelete=
{true|false}&enable={true|false}
See Generic signature conventions for an explanation of the conventions used in our generic signatures. Below is a brief description of each parameter.

Parameter Description

secToken The security token for this user’s current Arrayent Cloud session. Returned in response to userLogin.

devId The Device ID of the device to be monitored. This alert is only valid for this device. Retrieve Device IDs with getDeviceList.

action The action to take when the alert is triggered. For SMS alerts this value must be sms.

attrName Name of the device attribute to monitor.

operation The boolean operator to use when comparing attrNameagainst threshold. Valid values: <, <=, >, >=, regex (only valid for string attributes), equals (only valid for string attributes).

threshold The value to compare attrName against.

address The mobile phone number that the text message will be sent to. See below for phone number format.

msg The text message that will be sent to the recipient phone. Maximum 140 characters.

autoDisarm Optional. Default: true.

autoDisable Optional. Default: false.

autoDelete Optional. Default: false.

enable Enable or disable the alert. Optional. Default: true.
Phone Number Formats

When creating an SMS alert via addTrigger the value for the address argument must be a phone number in the following format

+<COUNTRY CODE><PHONE NUMBER>.

E.g. +33305967389 (for a phone number in France)

E.g. +16505551212 (for a phone number in the US).

Do not insert any spaces or special characters.
Examples

When led1 == 1 on device 9356 the text message led1==1 will be sent to the phone number +16506925478. Note that when the equals character (= ) occurs as an argument value it must be encoded to %3D.
https://DevKit-api.arrayent.com/zdk/services/zamapi/addTrigger?
secToken=91md95cl0&devId=9356&attrName=led1&operation=%3D%3D&threshold=1&
action=sms&address=+16506925478&msg=led1%3D%3D1&autoDisarm=true&autoDisable=
false&autoDelete=false&enable=true
When temperature > 100 on device 3782 the text message Hot! will be sent to the phone number +16504302299.
https://DevKit-api.arrayent.com/zdk/services/zamapi/addTrigger?
secToken=91md95cl0&devId=3782&attrName=temperature&operation=>&threshold=1&
action=sms&address=16506925478&msg=led1==1&autoDisarm=true&autoDisable=
false&autoDelete=false&enable=true
Retrieving SMS Alerts with getTriggerDetailListByUser

Use getTriggerDetailListByUser to retrieve the list of alerts that have been defined for a given user. This operation returns all alert definitions for all of the specified user’s devices. Below is the generic signature of a getTriggerDetailListByUser request.
https://<SUBDOMAIN>.arrayent.com/zdk/services/zamapi/
getTriggerDetailListByUser?secToken=<SECURITY TOKEN>&
userId=<USER ID>
See Generic signature conventions for an explanation of the conventions used in our generic signatures. getTriggerDetailListByUser will return an XML response similar to the following example:
<ns1:getTriggerDetailListByUserResponse xmlns:ns1="http://arrayent.com/zamapi/">
 <trigList>
 <triggerId>4012</triggerId>
 <devId>184553180</devId>
 <action>htmlemail</action>
 <attrName>movement</attrName>
 <operation>==</operation>
 <threshold>0</threshold>
 <address>joe@dirt.com</address>
 <msg>He's dead, Jim.</msg>
 <autoDisarm>true</autoDisarm>
 <disarmed>false</disarmed>
 <autoDelete>false</autoDelete>
 <autoDisable>false</autoDisable>
 <enable>true</enable>
 </trigList>
 <trigList>
 <triggerId>4012</triggerId>
 <devId>184553180</devId>
 <action>sms</action>
 <attrName>movement</attrName>
 <operation>==</operation>
 <threshold>0</threshold>
 <address>+16506922439</address>
 <msg>He's dead, Jim.</msg>
 <autoDisarm>true</autoDisarm>
 <disarmed>false</disarmed>
 <autoDelete>false</autoDelete>
 <autoDisable>false</autoDisable>
 <enable>true</enable>
 </trigList>
</ns1:getTriggerDetailListByUserResponse>
Each trigList element contains an alert definition. You can tell which alerts are SMS alerts by inspecting the value of action (which will be set to sms). The triggerId element represents a random integer which the Arrayent Cloud generated when the alert was created. You will need this ID if you want to modify or delete the alert definition. The devId element represents the device ID which the alert is defined for. The rest of the elements are fields that were set when the alert was created. See Creating SMS alerts with addTrigger above for a description of these elements.
Modifying SMS Alerts with updTrigger

Use updTrigger to update an existing alert definition. Below is the generic signature of an updTrigger request:
https://<SUBDOMAIN>.arrayent.com/zdk/services/zamapi/updTrigger?
secToken=<SECURITY TOKEN>&devId=<DEVICE ID>&action=sms&attrName=
<DEVICE ATTRIBUTE NAME>&operation={>|>=|<|<=|==|regex|equals}&
threshold=<THRESHOLD>&address=<PHONE NUMBER>&msg=<MESSAGE>&
autoDisarm={true|false}&autoDisable={true|false}&autoDelete=
{true|false}&enable={true|false}&triggerId=<TRIGGER ID>
See Generic signature conventions for an explanation of the conventions used in our generic signatures. The updTrigger signature is almost identical to the addTrigger signature, with the addition of one parameter called triggerId. This is a random integer generated by the Arrayent Cloud when the alert definition is created. Use getTriggerDetailListByUser to retrieve trigger IDs. See Retrieving SMS Alerts with getTriggerDetailListByUser for more information. See Creating SMS alerts with addTrigger for a description of the rest of the elements.
Deleting SMS Alerts

Use removeTrigger to delete a single alert. Below is the generic signature of a removeTrigger request:
https://<SUBDOMAIN>.arrayent.com/zdk/services/zamapi/removeTrigger?
secToken=<SECURITY TOKEN>&triggerId=<TRIGGER ID>
See Generic signature conventions for an explanation of the conventions used in our generic signatures. The triggerId parameter is the Trigger ID. This is a random integer which the Arrayent Cloud generated when the alert was created via addTrigger. See Retrieving SMS Alerts with getTriggerDetailListByUser above to learn how to retrieve alert definitions and their corresponding Trigger IDs. Use removeTriggersByDevice to delete all of the alert definitions that have been created for a given device. Below is the generic signature of a removeTriggersByDevice request:
https://<SUBDOMAIN>.arrayent.com/zdk/services/zamapi/
removeTriggersByDevice?secToken=<SECURITY TOKEN>&
devId=<DEVICE ID>
You can retrieve Device IDs with getDeviceList. Use removeTriggersByUser to delete all of the alert definitions that have been defined for all of the devices owned by a given user. Below is the generic signature for a removeTriggersByUser request:
https://<SUBDOMAIN>.arrayent.com/zdk/services/zamapi/
removeTriggersByUser?secToken=<SECURITY TOKEN>&userId=<USER ID>
When you log in to the Arrayent Cloud via userLogin the User ID for the current user is provided in the response.
Appendix
Generic signature conventions

In this guide we document the generic signatures of various web service operations. Below is an example of one such generic signature:
https://<SUBDOMAIN>.arrayent.com/zdk/services/zamapi/addTrigger?
secToken=<SECURITY TOKEN>&devId=<DEVICE ID>&action=sms&attrName=
<DEVICE ATTRIBUTE NAME>&operation={>|>=|<|<=|==|regex|equals}&
threshold=<THRESHOLD>&address=<PHONE NUMBER>&msg=<MESSAGE>&
autoDisarm={true|false}&autoDisable={true|false}&autoDelete=
{true|false}&enable={true|false}
Items in angle brackets (e.g. <SUBDOMAIN>) are placeholders.

Items in braces (e.g. {true|false}) represent a list of valid values. The vertical line character (|) serves as the delimiter between valid values (e.g. given {true|false} the valid values are true and false).

All other values are literal.