Send SMS Messages To Devices

Send an SMS Message to Devices:
POST /sms

Sends SMS messages to one or more devices.

Contents

See also:
Retrieve SMS Messages Sent by Devices
Start SMS Callback

Uses and Requirements

SMS 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 via the SMSDeliveryConfirmation callback service.

Request

HTTP Request

POST https://thingspace.verizon.com/api/m2m/v1/sms

Resource Path and Query Parameters

None.

Header Parameters

The request header must contain the current session token.

Parameter Name Data Type Description
VZ-M2M-Token
required
string A valid session token returned by POST /session/login.

Request Body

The request body identifies the devices that the message will be sent to, and the message itself.

Parameter Name Data Type Description
deviceIds
optional*
array of device identifiers The devices that you want to send the message to, specified by device identifier. You only need to provide one identifier per device. Do not use accountName, groupName, or customFields if you use this parameter.
kind,
id

required for deviceIds
strings The type and value of the device identifier.
  • ESN - decimal, 11 digits
  • ICCID - decimal, up to 20 digits
  • IMEI - decimal, up to 15 digits
  • MDN - decimal, 10 digits
  • MEID - hexadecimal, 14 characters
  • MSISDN - decimal, 11 digits
accountName
optional
string The name of a billing account. This parameters is only required if you are passing groupName and the UWS account used for the current API session has access to multiple billing accounts, because the same device group name can exist in multiple accounts.
An account name is usually numeric, and must include any leading zeros.
groupName
optional*
string The name of a device group, if you want to send the SMS message to all devices in the device group.
servicePlan
optional*
string The name of a service plan, if you want to only include devices that have that service plan. You can use GET /plans to get a list of all service plans in the account.
customFields
optional*
array of customField objects The names and values of custom fields, if you want to only include devices that have matching custom fields.
key
required for customFields
string The name of the custom field. Valid names are CustomField1, CustomField2, CustomField3, CustomField4, and CustomField5.
value
required for customFields
string The value of the custom field. The value is not case-sensitive, but other than that it must match exactly with the value set for a device. Wildcards and partial matches are not supported.
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 160 characters in 7-bit format, or 140 characters in 8-bit format.

* You can either specify up to 10,000 individual devices with the devices parameter, or you can use any combination of groupName, servicePlan, and customFields to run the request on all devices that match all criteria.

Example Request Body

Send an SMS Message to Single Device

{
  "deviceIds": [
    {
      "id": "89148000000800139708",
      "kind": "iccid"
    }
  ],
  "smsMessage": "Can you hear me now?"
}

Send an SMS Message to All Devices with a Specified Service Plan

{
  "servicePlan": "T Plan 2",
  "smsMessage": "The rain in Spain stays mainly in the plain."
}

Success Responses

Status 200

Parameter Name Data 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.

Example Success Response

{
  "requestId": "595f5c44-c31c-4552-8670-020a1545a84d"
}

Example Success Callback Response

SendSmsMessage Callback Messages

Per-Device Message

{  
  "username":"",
  "password":"",
  "requestId":"2c90bd28-ece4-42ef-9f02-7e3bd4fbff33",
  "deviceIds":[  
    {  
      "id":"89148000001134816189",
      "kind":"Iccid"
    },
    {  
      "id":"5096307971",
      "kind":"Mdn"
    },
    {  
      "id":"990000475989473",
      "kind":"Imei"
    },
    {  
      "id":"15096307971",
      "kind":"Msisdn"
    }
  ],
  "comment":"SendSmsMessage,Performed action on device.",
  "status":"Success",
  "callbackCount":1,
  "maxCallbackThreshold":4
}

Request Complete Message

{  
  "username":"",
  "password":"",
  "requestId":"2c90bd28-ece4-42ef-9f02-7e3bd4fbff33",
  "comment":"SendSmsMessage,Request Completed Processing."
  "summary": { 
    "devicesRequested": 2
  }
}

SmsDeliveryConfirmation Callback Messages

Success after device acknowledgement

{  
  "username":"",
  "password":"",
  "requestId":"2c90bd28-ece4-42ef-9f02-7e3bd4fbff33",
  "deviceIds":[  
    {  
      "id":"5096307971",
      "kind":"Mdn"
    }
  ],
  "deviceResponse":{  
    "smsDeliveryResponse":{  
      "confirmation":"Delivered"
    }
  }
}

Undelivered, such as for messages sent to suspended devices

{  
  "username":"",
  "password":"",
  "requestId":"2c90bd28-ece4-42ef-9f02-7e3bd4fbff33",
  "deviceIds":[  
    {  
      "id":"5096307971",
      "kind":"Mdn"
    }
  ],
  "deviceResponse":{  
    "smsDeliveryResponse":{  
      "confirmation":"Undelivered"
    }
  }
}

Expired, when a message could not be delivered within 5 days

{  
  "username":"",
  "password":"",
  "requestId":"2c90bd28-ece4-42ef-9f02-7e3bd4fbff33",
  "deviceIds":[  
    {  
      "id":"5096307971",
      "kind":"Mdn"
    }
  ],
  "deviceResponse":{  
    "smsDeliveryResponse":{  
      "confirmation":"Expired"
    }
  }
}

Rejected, when a device’s message queue is full (the device already has 100 pending messages in queue)

{  
  "username":"",
  "password":"",
  "requestId":"2c90bd28-ece4-42ef-9f02-7e3bd4fbff33",
  "deviceIds":[  
    {  
      "id":"5096307971",
      "kind":"Mdn"
    }
  ],
  "deviceResponse":{  
    "smsDeliveryResponse":{  
      "confirmation":"Rejected"
    }
  }
}

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!