GetSmsMessages

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

SMS Message Handling

Mobile-originated SMS messages 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 GetSmsMessages request, the M2M Platform sends queued messages as a list. To ensure that messages are not lost, they remain in the queue until your application explicitly acknowledges that it received them by sending another request that contains the Token value from the response.

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

  1. Mobile-Originated SMS message is sent by a device to 750075007500 and is received by the ThingSpace Platform.
  2. The ThingSpace Platform attempts to deliver the message via the EnhancedConnectivityService callback.
  3. If delivery fails, or of the account has not registered for EhnancedConnectivityService callbacks, the message is stored in a queue on the ThingSpace Platform.
  4. Another mobile-originated SMS is sent by a device.
  5. The ThingSpace Platform attempts to deliver the new message via the callback.
  6. If delivery again fails, the message is stored in the queue.
  7. If your application sends a GetSmsMessages request, any queued messages are sent in a synchronous response. If your application sends a StartSmsCallback 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 StartSmsCallback or GetSmsMessages 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 call to GetSmsMessages returns up to 100 SMS messages. If there are more than 100 SMS messages waiting in the queue for the specified account, you must call GetSmsMessages repeatedly to retrieve all of those messages, using the PreviousToken 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 Parameters

Parameter Type Description
AccountName
required		 string An account name. SMS messages that were sent from devices associated with this account will be retrieved.
PreviousToken
optional		 string

The Token returned by the previous call to this API, if any.

  • For the first request, leave this element empty to retrieve the first set of messages.
  • If the response contains any messages, call the API again with the token from the response to acknowledge receiving that set of messages and to request the next set.
  • Continue sending requests with the latest Token value until you receive a response that doesn't contain any SMS messages, which indicates that you have received all of the messages.

Response Parameters

Parameter Type Description
RetrievedSmsMessages RetrievedSmsMessage A list of up to 100 SMS messages that were sent by devices in the account.
Device DeviceIdentifierCollection Identifiers for the device that sent the message.
DeviceIdentifiers DeviceIdentifier One or more identifiers for the device.
Kind string The type of the device identifier. Valid types of identifiers are:
  • ESN (decimal)
  • ICCID (up to 20 digits)
  • IMEI (up to 16 digits)
  • MDN
  • MEID (hexadecimal)
  • MIN
  • MSISDN
Identifier string The value of the device identifier.
Message string The contents of the SMS message.
Timestamp dateTime The date and time that the message was received by the Verizon ThingSpace Platform.
Token string A token that uniquely identifies the set of messages that were returned. To ensure reliability, they will not be removed from the queue until you call this API again and pass this value in the PreviousToken field.

Example SOAP Request 

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
  xmlns:v2="http://nphase.com/unifiedwebservice/v2"
  xmlns:nph="http://schemas.datacontract.org/2004/07/NPhase.UnifiedWebService.APIs.v2.Contract.EnhancedConnectivityService">
  <soapenv:Header>
    <v2:token>a56832d9-b870-4e5d-85b8-57003a592a01</v2:token>
  </soapenv:Header>
  <soapenv:Body>
    <v2:GetSmsMessages>
      <v2:Input>
        <nph:AccountName>account_name</nph:AccountName>
        <nph:PreviousToken></nph:PreviousToken>
      </v2:Input>
    </v2:GetSmsMessages>
  </soapenv:Body>
</soapenv:Envelope>

Example SOAP Response

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
  <s:Body>
    <GetSmsMessagesResponse xmlns="http://nphase.com/unifiedwebservice/v2">
      <Output xmlns:i="http://www.w3.org/2001/XMLSchema-instance"
xmlns:a="http://schemas.datacontract.org/2004/07/NPhase.UnifiedWebService.APIs.v2.Contract.EnhancedConnectivityService">
        <a:RetrievedSmsMessages>
          <a:RetrievedSmsMessage>
            <a:Device xmlns:b="http://schemas.datacontract.org/2004/07/NPhase.UnifiedWebService.APIs.v2.Contract.Common">
              <b:DeviceIdentifiers>
                <b:DeviceIdentifier>
                  <b:Kind>esn</b:Kind>
                  <b:Identifier>09613489171</b:Identifier>
                </b:DeviceIdentifier>
                <b:DeviceIdentifier>
                  <b:Kind>mdn</b:Kind>
                  <b:Identifier>8587757416</b:Identifier>
                </b:DeviceIdentifier>
              </b:DeviceIdentifiers>
            </a:Device>
            <a:Message>testmessage1</a:Message>
            <a:TimeStamp>2013-07-15T12:29:49.5815306-05:00</a:TimeStamp>
          </a:RetrievedSmsMessage>
          <a:RetrievedSmsMessage>
            <a:Device xmlns:b="http://schemas.datacontract.org/2004/07/NPhase.UnifiedWebService.APIs.v2.Contract.Common">
              <b:DeviceIdentifiers>
                <b:DeviceIdentifier>
                  <b:Kind>esn</b:Kind>
                  <b:Identifier>09613489171</b:Identifier>
                </b:DeviceIdentifier>
                <b:DeviceIdentifier>
                  <b:Kind>mdn</b:Kind>
                  <b:Identifier>8587757416</b:Identifier>
                </b:DeviceIdentifier>
              </b:DeviceIdentifiers>
            </a:Device>
            <a:Message>testmessage2</a:Message>
            <a:TimeStamp>2013-07-15T13:29:49.5815306-05:00</a:TimeStamp>
          </a:RetrievedSmsMessage>
        </a:RetrievedSmsMessages>
        <a:Token>363b9b80-440e-4431-98b8-357b6208b331</a:Token>
      </Output>
    </GetSmsMessagesResponse>
  </s:Body>
</s:Envelope>

Request Schema Diagram

Response Schema Diagram