Get SMS Messages

`GET /sms/{accountName}/history`

Retrieves queued SMS messages sent by all M2M devices associated with a billing account.

Bulk operation: Not Supported

eSIM profiles: Both Verizon US and Global

Get SMS Messages Sent by Devices:
GET /sms/{accountName}/history

SMS Message Handling

Mobile-originated SMS messages from devices are stored in a queue in the ThingSpace Platform if they cannot be delivered to your application immediately via the EnhancedConnectivityService callback. When your application sends a GET /sms request, the ThingSpace Platform sends queued messages. To ensure that messages are not lost, they remain in the queue until your application explicitly acknowledges that they were received by sending another request that contains the Token value from the response.

Here is the general flow for mobile-originated SMS messages:

A Mobile-Originated SMS message is sent by a device to 900060005010 and is received by the ThingSpace Platform.
The ThingSpace Platform attempts to deliver the message via the DeviceMessages callback.
If delivery fails, the message is stored in a queue on the ThingSpace Platform.
Another mobile-originated SMS is sent by a device.
The ThingSpace Platform attempts to deliver the new message via the callback.
If delivery again fails, the message is stored in the queue.
If your application sends a GET /sms request, any queued messages are sent in a synchronous response. If your application sends a PUT /sms/{accountName}/startcallbacks request, any queued messages are sent to the registered EnhancedConnectivityService callback URL.

When your EnhancedConnectivityService callback listener is working, new SMS messages received from devices will be sent as soon as they are received by the ThingSpace Platform. Any queued messages are not sent automatically; you must use PUT /sms/{accountName}/startcallbacks or GET /sms to retrieve those messages from the queue.

The SMS messages may be received out of order, relative to the order in which they were sent.

Retrieving Large Numbers of SMS Messages

Each GET /sms request returns up to 100 SMS messages. If there are more than 100 SMS messages waiting in the queue for the specified account, you must send additional GET requests to retrieve all of those messages, using the next parameter to acknowledge receipt of the previous block of messages and request the next block. If there are errors in transmitting or acknowledging messages, the affected messages remain in the queue until they are successfully transmitted and acknowledged.

Request Components

HTTP Request

`GET https://thingspace.verizon.com/api/m2m/v1/sms/{accountName}/history`

Resource Path and Query Parameters

You must include the account name in the path. Use the next parameter to acknowledge receipt of the previous block of messages, and to request the next block. The value to use is returned in the Location header of a successful response.

Parameter Name	Data Type	Description
accountName required	string	The name of the billing account for which you want to retrieve SMS messages. An account name is usually numeric, and must include any leading zeros.
next optional	string	The next value returned in the Location header of the previous GET response, if any. For the first request, do not include this parameter to retrieve the first set of messages. If the response contains any messages, use the URL from the Location header in the response to send another GET request, which will acknowledge receiving that set of messages and request the next set. The Location URL contains the correct value for the next parameter. Continue sending requests with the latest Location URL until you receive a response that doesn’t contain any SMS messages, which indicates that you have received all of the messages.

Header Parameters

The request header must contain a current ThingSpace authorization bearer token and a valid VZ-M2M session token, and must set the content-type to JSON.

Parameter Name	Data Type	Description
Authorization required	string	HTTP Authorization bearer token.
VZ-M2M-Token required	string	A valid session token returned by POST /session/login.
Content-Type required	string	Must be `application/json`.

Request Body

None.

Success Responses

Status 200 or 202

Parameter Name	Data Type	Description
messages	array of devices, messages, and timestamps	An array of up to 100 SMS messages that were sent by devices in the account.
deviceIds	array of device IDs	One or more IDs of the device that sent the message.
id	string	The value of the device identifier.
kind	string	The type of the device identifier. Valid types are: ESN (decimal) ICCID (up to 20 digits) IMEI (up to 15 digits) MDN MEID (hexadecimal) MSISDN
message	string	The contents of the SMS message.
timestamp	dateTime	The date and time that the message was received by the Verizon ThingSpace Platform.
hasMoreData	boolean	False for a status 200 response. True for a status 202 response, indicating that there is more data to be retrieved. Send another request and include the `next` parameter to get the next block of messages.

Example Success Response

{
  {
    "messages": [
      {
        "deviceIds": [
          {
            "id": "11-digit ESN",
            "kind": "esn"
          }
        ],
        "message": "testmessage1",
        "timestamp": "2016-01-01T12:29:49-08:00"
      },
      {
        "deviceIds": [
          {
            "id": "11-digit ESN",
            "kind": "esn"
          }
        ],
        "message": "testmessage2",
        "timestamp": "2016-01-01T12:31:02-08:00"
      }
    ]
  },
  "hasMoreData": false
}

Failure Responses

Status 400

All error messages are returned in this format:

{
  "errorCode": "error code string",
  "errorMessage": "error message string"
}

Error codes and messages are listed on the Error Messages page, along with explanations and suggestions for corrective actions

Try It Out!