sms.history

The sms.history command is used to obtain historical SMS messages.

SMS history is requested by specifying:

A definite time period using a start and end date
A time period defined by the "last period of time" style query (last "24h", etc.)
A last number of records
no identifiers to return the SMS history of the whole organization
Tags. For more information on Tags, see Using Tags
Array of ids
Content of a text message

TR50 Request

Definite Time Period

// Definite time period request
{
    "1": {
        "command": "sms.history",
        "params": {
            "msisdn": "mymsisdn",
            "start": "2017-01-01T00:00:00Z",
            "end": "2017-01-31T23:59:59Z",
            "offset": 0,
            "limit": 50,
            "sort": "-dateSent",
            "direction": "mo"
        }
    }
}

Last period of time

 // Last period of time request
{
    "1": {
        "command": "sms.history",
        "params": {
            "msisdn": "mymsisdn",
            "last": "24h",
            "offset": 0,
            "limit": 50,
            "sort": "-dateSent"
        }
    }
}

Last number of records

// Last number of records request
{
    "1": {
        "command": "sms.history",
        "params": {
            "msisdn": "mymsisdn",
            "records": 100,
            "offset": 0,
            "sort": "-dateSent",
        }
    }
}

With no identifiers

// No identifiers are set then the SMS history of the entire organization will be returned for the specific period specified
{
    "1": {
        "command": "sms.history",
        "params": {
            "start": "2017-12-01T00:00:00Z",
            "end": "2018-01-31T23:59:59Z"
        }
    }
}

Based on Tags

// Based on Tags
{
  "1": {
      "command": "sms.history",
      "params": {
            "start": "2017-12-01T00:00:00Z",
            "end": "2018-01-31T23:59:59Z",
            "tags":"career1"
          }
  }
}

Array of ids

// Array of ids
{
  "1": {
      "command": "sms.history",
      "params": {
            "start": "2017-12-01T00:00:00Z",
            "end": "2018-01-31T23:59:59Z",
            "id": ["59962ef7fe2a133569421d26", "59261f811c5bd72b33e800c7"]
      }
  }
}

Content of a Message

// Content of a Message
{
  "1": {
      "command": "sms.history",
      "params": {
            "start": "2017-12-01T00:00:00Z",
            "end": "2018-01-31T23:59:59Z",
            "message": "\"Message for the second template\""
      }
  }
}

Request Parameters

Name	Type	Required	Description
thingKey	String	Yes*	Identifies the connection for which the SMS history is to be acquired.
esn	String		Identifies the connection for which the SMS history is to be acquired.
iccid	String		Identifies the connection for which the SMS history is to be acquired.
imei	String		Identifies the connection for which the SMS history is to be acquired.
imsi	String		Identifies the connection for which the SMS history is to be acquired.
meid	String		Identifies the connection for which the SMS history is to be acquired.
msisdn	String		Identifies the connection for which the SMS history is to be acquired.
*One of the above parameters is required.
start	String		When doing a definite time period request this is the timestamp for the start of the specified time window.
end	String		When doing a definite time period request this is the timestamp for the end of the specified time window.
last	String		When doing a last period of time request this specifies the last X amount of time in seconds (s), minutes (m), hours (h), or days (d).
records	Integer		When doing a last number of records request this specifies the number of records to return. A value of zero returns the global maximum number of records.
offset	Integer		The starting record offset, used for pagination. Defaults to 0 if not specified.
limit	Integer		Limits the number of results returned. Defaults to the maximum configured size.
sort	String		A string indicated the direction (+ for ascending, - for descending) and column to sort the results by. To sort by the dateSend descending, use "-dateSent".
direction	String		Filter the results of the history based on the direction of the message. The direction is either "mo" for mobile orginated messages or "mt" for mobile terminated messages. If omitted, both mobile originated and mobile terminated messages will be returned.
external	Boolean		The external command is an optional boolean field (defaulted to false), that when it is set to true, will only return sms records that are not associated with a connection. Otherwise it will not perform this type of filtering.

TR50 Response

If the command is sent successfully a success message and the history records found are returned. Otherwise, an error and error message will be returned.

The number of records returned is limited by the M2M Service. In cases where your selection has more results than the limit of the deviceWISE Cloud, you should shorten your time window or lower the number of records you are requesting.

{
  "1": {
    "success": true,
    "params": {
      "count": 321,
      "values": [
        {
          "id": "531c907b5d80f1330c238757",
          "orgId": "533ef123310046187700007f",
          "connId": "578e3232a681fdc03520dfa66",
          "uuid": "534e49181c5bd5328cd57539",
          "esn": "",
          "from": "463191003136461",
          "to": "700092",
          "type": "mo",
          "message": "The message",
          "msisdn": "453291003336461",
          "dateSent": "2017-12-05T13:26:32.769Z",
          "status": "received",
          "statusRaw": "RECEIVED"
	   "validity": 1200							
        },
        ...
      ]
    }
  }
}

Response Parameters

Name	Type	Description
count	Integer	The total number of matching records.
values	Array	The array of history records.

Value Array Object

Name	Type	Description
id	String	The id is the unique identifier for each and every SMS record. In the case of a Sharing Things and Connections, a duplicate SMS will be created for each organization the connection is shared to and each SMS will have a different id
uuid	String	The uuid is the identifier for each SMS sent through the SMS engine. In the case of Sharing Things and Connections, there will be a duplicate SMS record for each organization the connection is shared to and each record will share the same uuid.
msisdn	String	The MSISDN of the target.
user	String	The user who sent the message
dateSent	String	The date the SMS was initially sent
to	String	The ID of the connection the message was sent to.
type	String	The type of message "mo" for mobile orginated messages and "mt" for mobile terminated messages
message	String	The message.
encoding	String	The encoding type: SEVEN_BIT, EIGHT_BIT, UCS2, etc.
from	String	A string identifying the sender or source of the SMS.
preferredSmsc	String	The preferred SMSC: tele2, att, etc.
routingPlan	String
priority	Integer	Integer from 0 (highest priority) to 10.
delivery	Boolean	If true, delivery messages will be produced.
status	String	The textual description of the status of the message.
statusRaw	String	The raw, unrefined status string.
validity	Integer	The amount of time the SMS is attempted to be transmitted.
statusHistory	Array	An array containing the status changes of the SMS message as it traveled to it's destination.
deliveredTime	String	The date/time of delivery.
failedTime	String	The date/time of delivery failure.

StatusHistory Array Object

Name	Type	Description
status	String	The textual description of the status of the message.
statusRaw	String	The raw, unrefined status string.
text	String	A field containing additional status information.
ts	String	The date/time of the status update.