SendSmsMessage

Sends an SMS message to one or more devices.

Uses and Requirements

The messages are queued on the ThingSpace Platform and sent as soon as possible, but they may be delayed due to traffic and routing considerations. You can register for the EnhancedConnectivityService callback service to be notified when the messages have actually been sent to the devices, and for the SMSDeliveryConfirmation callback service to verify that the devices receive the messages.

The Verizon Wireless network will attempt to deliver a message for five days (120 hours) from the date of receipt. Messages not delivered within five days will be deleted, and an "expired" notification will be sent to your registered callback service.

Request Parameters

Parameter Type Description
Devices
optional*		 DeviceIdentifier

A list of one or more devices that you want to send the message to, specified by device identifier.

Do not pass DeviceGroupName, AccountName, or any of the filters if you use this parameter.

NOTE: can use GetDeviceList to get a list of all devices in the account.

Kind
required for Devices		 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)
  • MSISDN
Identifier
required for Devices		 string The value of the device identifier.
DeviceGroupName
optional*		 string The name of a device group, if you want to send the SMS message to all devices in the device group.
AccountName
optional*		 string

The name of the billing account that is associated with the specified device group and/or the specified device. If you have access to multiple billing accounts, you must specify an account name, since the same device group name can be used in multiple accounts.

An account name is usually numeric, and must include any leading zeros.
DeviceServicePlanFilter
optional*		 string The name of a service plan, if you want to only include devices that have that service plan. You can use GetServicePlanList to get a list of all service plans in the account.
DeviceCustomFieldFilter
optional*		 CustomFieldFilterObject The names and values of custom fields, if you want to only include devices that have matching custom fields.
Name
required for DeviceCustomFieldFilter		 string The name of the custom field. Valid names are CustomField1, CustomField2, CustomField3, CustomField4, and CustomField5.
Value
required for DeviceCustomFieldFilter		 string The value of the custom field.

Allowed characters in custom field values:

  • Alphanumeric characters
  • / (forward slash)
  • SPACE
  • @ (at sign)
  • . (period)
  • , (comma)
  • : (colon)
  • - (hyphen)
  • _ (underscore)
  • ( (open parenthesis)
  • ) (close parenthesis)
  • [ (open bracket)
  • ] (close bracket)
  • # (number sign or hash)
DataEncoding
optional		 string

The SMS message encoding, which can be:

  • 7-bit (default)
  • 8-bit-ASCII
  • 8-bit-UTF-8
  • 8-bit-DATA

Note: All 8-bit SMS messages require the message contents to be base64 encoded.
SmsMessage
required		 string The contents of the SMS message. The SMS message is limited to 140 bytes (160 characters in 7-bit format, or 140 characters in 8-bit format).

* You can either specify individual devices with the Devices parameter, or you can run the request on all devices that have a specified account name, device group name, service plan name, or custom field value. You can specify an AccountName or a DeviceGroupName plus one or both filters to identify only those devices that match all criteria.

Response Parameters

Parameter Type Description
RequestId string

A unique string that associates the request with the results that are sent via a callback service.

The ThingSpace Platform will send a separate callback message for each device that matched the request criteria, indicating whether the operation succeeded for that device and containing any requested information. All of the callback messages will have the same RequestId.

Callback Response Parameters

Several different callback messages are returned as SMS messages are sent to devices.

EnhancedConnectivityService Callback Parameters

NOTE: The key elements in the callback message are the device identifier and the Comment, which will be populated with information about the status of the request.

Parameter Type Description
CallbackRequest CallbackRequest Wrapper element for all callback elements.
Username string The username defined when a URL was registered for the callback service, or an empty element if no username was defined.
Password string The password defined when a registered for the callback service, or an empty element if no password was defined.
RequestId string A unique string that matches the RequestId returned in the synchronous response to the original API request.
Device DeviceIdentifier Identifiers for the device in device-specific callbacks. This element is not included in "Completed Processing" callbacks.
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.
Data CallbackData The data elements for this callback.
CarrierService CarrierServiceCallbackRequest Null for this callback service.
ExternalProvisioningChange ExternalProvisioningChange Null for this callback service.
PromoChange PromoChange Null for this callback service.
SMSDelivery SMSDelivery Null for this callback service.
PRLInformation PRLInformation Null for this callback service.
GoToState DeviceSuspendStatus Null for this callback service.
Fault SoapFault Information about any errors that may have occurred.
faultcode QName
faultstring string
faultfactor anyURI
detail
Comment string Information about the status of the request, such as "SendSmsMessage, Performed action on device."
Summary SummaryReport Null in per-device messages, but contains NumDevicesRequested element in Request Complete message.
Status string Null for this callback service.
CallbackCount integer The number of times this callback message has been sent.
MaxCallbackThreshold integer The maximum number of times this callback message will be sent if it is not correctly acknowledged.

SMSDeliveryConfirmation Callback Parameters

Parameter Type Description
CallbackRequest CallbackRequest Wrapper element for all callback elements.
Username string The username defined when a URL was registered for the callback service, or an empty element if no username was defined.
Password string The password defined when a registered for the callback service, or an empty element if no password was defined.
RequestId string A unique string that matches the RequestId returned in the synchronous response to the original API request.
Device DeviceIdentifier Identifiers for the device in device-specific callbacks. This element is not included in "Completed Processing" callbacks.
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.
Data CallbackData The data elements for this callback.
CarrierService CarrierServiceCallbackRequest Null for this callback service.
ExternalProvisioningChange ExternalProvisioningChange Null for this callback service.
PromoChange PromoChange Null for this callback service.
SMSDelivery SMSDelivery Contains the confirmation message.
Confirmation string

The status of the message delivery attempt:

  • "Delivered" for successful deliveries.
  • "Undeliverable" for messages sent to suspended devices.
  • "Expired" when the message could not be delivered within 5 days, such as when a device is off.
  • "Rejected" when a device's message queue is full (the device already has 100 pending messages in queue).
Fault SoapFault Information about any errors that may have occurred. Null if no errors.
faultcode QName
faultstring string
faultfactor anyURI
detail
PRLInformation PRLInformation Null for this callback service.
GoToState DeviceSuspendStatus Null for this callback service.
Fault SoapFault Information about any errors that may have occurred. Null if no errors.
faultcode QName
faultstring string
faultfactor anyURI
detail
Comment string Null for this callback request.
Summary SummaryReport Null for this callback request.
Status string Null for this callback service.
CallbackCount integer The number of times this callback message has been sent.
MaxCallbackThreshold integer The maximum number of times this callback message will be sent if it is not correctly acknowledged.

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"
xmlns:nph1="http://schemas.datacontract.org/2004/07/NPhase.UnifiedWebService.APIs.v2.Contract.Common">
   <soapenv:Header>
      <token xmlns="http://nphase.com/unifiedwebservice/v2">${#Project#Token}</token>
   </soapenv:Header>
   <soapenv:Body>
      <v2:SendSmsMessage>
         <v2:Input>
            <nph:Devices>
               <nph1:DeviceIdentifier>
                  <nph1:Kind>MDN</nph1:Kind>
                  <nph1:Identifier>7022895555</nph1:Identifier>
               </nph1:DeviceIdentifier>
            </nph:Devices>
            <nph:DataEncoding>7-bit</nph:DataEncoding>
            <nph:SmsMessage>Status</nph:SmsMessage>
         </v2:Input>
      </v2:SendSmsMessage>
   </soapenv:Body>
</soapenv:Envelope>

Example SOAP Response

<SendSmsMessageResponse 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:RequestId>2c90bd28-ece4-42ef-9f02-7e3bd4fbff33</a:RequestId>
   </Output>
</SendSmsMessageResponse>

Example Callback Messages

SendSmsMessage Callback Messages

Per-Device Message

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
  <s:Body xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <CallbackRequest xmlns="http://nphase.com/unifiedwebservice/v2">
      <Username/>
      <Password/>
      <RequestId>2ca8790f-7925-47e5-8367-dc5111ef92c4</RequestId>
      <Device>
        <Kind>meid</Kind>
        <Identifier>A100001F702731</Identifier>
      </Device>
      <Data>
        <Data>
          <CarrierService xsi:nil="true"/>
          <ExternalProvisioningChange xsi:nil="true"/>
          <PromoChange xsi:nil="true"/>
          <SMSDelivery xsi:nil="true"/>
          <PRLInformation xsi:nil="true"/>
          <GoToState xsi:nil="true"/>
          <Fault xsi:nil="true"/>
          <Comment>SendSmsMessage,Performed action on device.</Comment>
          <Summary xsi:nil="true"/>
          <Status xsi:nil="true"/>
          <CallbackCount>1</CallbackCount>
          <MaxCallbackThreshold>4</MaxCallbackThreshold>
        </Data>
      </Data>
    </CallbackRequest>
  </s:Body>
</s:Envelope>

Request Complete Message

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
  <s:Body xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <CallbackRequest xmlns="http://nphase.com/unifiedwebservice/v2">
      <Username/>
      <Password/>
      <RequestId>2ca8790f-7925-47e5-8367-dc5111ef92c4</RequestId>
      <Data>
        <Data>
          <CarrierService xsi:nil="true"/>
          <ExternalProvisioningChange xsi:nil="true"/>
          <PromoChange xsi:nil="true"/>
          <SMSDelivery xsi:nil="true"/>
          <PRLInformation xsi:nil="true"/>
          <GoToState xsi:nil="true"/>
          <Fault xsi:nil="true"/>
          <Comment>SendSmsMessage,Request Completed Processing</Comment>
          <Summary>
            <NumDevicesRequested>5</NumDevicesRequested>
          </Summary>
          <Status xsi:nil="true"/>
          <CallbackCount>1</CallbackCount>
          <MaxCallbackThreshold>4</MaxCallbackThreshold>
        </Data>
      </Data>
    </CallbackRequest>
  </s:Body>
</s:Envelope>

SmsDeliveryConfirmation Success Callback Message

This message is sent when a device acknowledges receipt of an SMS message.

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
  <s:Body xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <CallbackRequest xmlns="http://nphase.com/unifiedwebservice/v2">
      <Username/>
      <Password/>
      <RequestId>be1f03b8-64ec-4e59-a778-20536016beb5</RequestId>
      <Device>
        <Kind>MDN</Kind>
        <Identifier>8589268379</Identifier>
      </Device>
      <Data>
        <Data>
          <CarrierService xsi:nil="true"/>
          <ExternalProvisioningChange xsi:nil="true"/>
          <PromoChange xsi:nil="true"/>
          <SMSDelivery>
            <Confirmation>Delivered</Confirmation>
            <Fault xsi:nil="true"/>
          </SMSDelivery>
          <PRLInformation xsi:nil="true"/>
          <GoToState xsi:nil="true"/>
          <Fault xsi:nil="true"/>
          <Comment xsi:nil="true"/>
          <Summary xsi:nil="true"/>
          <Status xsi:nil="true"/>
          <CallbackCount>1</CallbackCount>
          <MaxCallbackThreshold>4</MaxCallbackThreshold>
        </Data>
      </Data>
    </CallbackRequest>
  </s:Body>

SmsDeliveryConfirmation Undeliverable Callback Message

This message is sent when an SMS message is sent to a suspended device.

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
  <s:Body xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <CallbackRequest xmlns="http://nphase.com/unifiedwebservice/v2">
      <Username/>
      <Password/>
      <RequestId>be1f03b8-64ec-4e59-a778-20536016beb5</RequestId>
      <Device>
        <Kind>MDN</Kind>
        <Identifier>8589268379</Identifier>
      </Device>
      <Data>
        <Data>
          <CarrierService xsi:nil="true"/>
          <ExternalProvisioningChange xsi:nil="true"/>
          <PromoChange xsi:nil="true"/>
          <SMSDelivery>
            <Confirmation>Unceliverable</Confirmation>
            <Fault xsi:nil="true"/>
          </SMSDelivery>
          <PRLInformation xsi:nil="true"/>
          <GoToState xsi:nil="true"/>
          <Fault xsi:nil="true"/>
          <Comment xsi:nil="true"/>
          <Summary xsi:nil="true"/>
          <Status xsi:nil="true"/>
          <CallbackCount>1</CallbackCount>
          <MaxCallbackThreshold>4</MaxCallbackThreshold>
        </Data>
      </Data>
    </CallbackRequest>
  </s:Body>
</s:Envelope>

SmsDeliveryConfirmation Expired Callback Message

This message is sent when an SMS message could not be delivered to a device within 120 hours (5 days) after it was sent.

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
  <s:Body xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <CallbackRequest xmlns="http://nphase.com/unifiedwebservice/v2">
      <Username/>
      <Password/>
      <RequestId>be1f03b8-64ec-4e59-a778-20536016beb5</RequestId>
      <Device>
        <Kind>MDN</Kind>
        <Identifier>8589268379</Identifier>
      </Device>
      <Data>
        <Data>
          <CarrierService xsi:nil="true"/>
          <ExternalProvisioningChange xsi:nil="true"/>
          <PromoChange xsi:nil="true"/>
          <SMSDelivery>
            <Confirmation>Expired</Confirmation>
            <Fault xsi:nil="true"/>
          </SMSDelivery>
          <PRLInformation xsi:nil="true"/>
          <GoToState xsi:nil="true"/>
          <Fault xsi:nil="true"/>
          <Comment xsi:nil="true"/>
          <Summary xsi:nil="true"/>
          <Status xsi:nil="true"/>
          <CallbackCount>1</CallbackCount>
          <MaxCallbackThreshold>4</MaxCallbackThreshold>
        </Data>
      </Data>
    </CallbackRequest>
  </s:Body>
</s:Envelope>

Request Schema Diagram

Response Schema Diagram