Send SMS Messages To Devices:

POST /sms

Sends SMS messages to one or more devices on your ThingSpace-enabled account.

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 attempts to deliver a message for five days (120 hours) from the date of receipt. Messages not delivered within five days are deleted, and an “expired” notification is 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 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

The request body identifies the devices that the message is 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
required
string The name of a billing account. This parameter is always required.
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 sends 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 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!